Receiving Inbound Webhooks

Learn how to set up your systems to receive and process webhook notifications from EventWaivers.

Overview

When events occur in EventWaivers (like a waiver being signed), the system can send webhook notifications to your application. This guide explains how to properly receive, validate, and process these webhook payloads.

Step-by-step

1. Create a webhook endpoint

   First, create an endpoint in your application that can receive POST requests. This should be a publicly accessible URL that EventWaivers can reach.

   Example endpoint in different frameworks:

   // Laravel example
   Route::post('/webhooks/eventwaivers', [WebhookController::class, 'handle']);
   

   // Node.js/Express example
   app.post('/webhooks/eventwaivers', (req, res) => {
     // Process webhook
     res.status(200).send('Webhook received');
   });
   

   # Python/Flask example
   @app.route('/webhooks/eventwaivers', methods=['POST'])
   def handle_webhook():
       # Process webhook
       return 'Webhook received', 200
   

2. Verify webhook authenticity

   Always verify that webhooks are genuinely from EventWaivers by checking the signature:

   // PHP example
   function verifySignature($payload, $signature, $secret) {
       $expectedSignature = hash_hmac('sha256', $payload, $secret);
       return hash_equals($expectedSignature, $signature);
   }
   
   // In your webhook handler
   $payload = file_get_contents('php://input');
   $signature = $_SERVER['HTTP_X_EVENTWAIVERS_SIGNATURE'] ?? '';
   
   if (!verifySignature($payload, $signature, $webhookSecret)) {
       http_response_code(401);
       exit('Invalid signature');
   }
   

   

3. Parse the webhook payload

   The webhook payload is sent as JSON in the request body. Parse it to access the event data:

   // PHP example
   $payload = file_get_contents('php://input');
   $data = json_decode($payload, true);
   
   $eventType = $data['event_type'];
   $eventData = $data['data'];
   

4. Handle different event types

   Process the webhook based on the event type:

   // PHP example
   switch ($eventType) {
       case 'waiver.signed':
           handleWaiverSigned($eventData);
           break;
       case 'waiver.updated':
           handleWaiverUpdated($eventData);
           break;
       case 'email.verified':
           handleEmailVerified($eventData);
           break;
       default:
           // Unknown event type
           break;
   }
   

5. Respond properly to the webhook

   Always respond with a 200 status code if you've received the webhook, even if you encounter errors in processing it:

   // PHP example
   http_response_code(200);
   echo json_encode(['status' => 'received']);
   

   This prevents EventWaivers from unnecessarily retrying webhook delivery.

6. Implement idempotency

   Webhooks may be sent multiple times for the same event (due to retries), so make your processing idempotent:

   // PHP example
   function handleWaiverSigned($data) {
       $signatureId = $data['signature_id'];
   
       // Check if we've already processed this signature
       if (alreadyProcessed($signatureId)) {
           return; // Skip processing
       }
   
       // Process the signature
       processSignature($data);
   
       // Mark as processed
       markAsProcessed($signatureId);
   }
   

7. Set up error logging

   Implement robust error logging to troubleshoot webhook issues:

   // PHP example
   try {
       processWebhook($data);
   } catch (Exception $e) {
       // Log the error but still return 200
       logError('Webhook processing failed: ' . $e->getMessage(), [
           'event_type' => $eventType,
           'event_id' => $data['id']
       ]);
   
       http_response_code(200); // Still acknowledge receipt
       echo json_encode(['status' => 'error', 'message' => 'Processing failed']);
   }
   

Notes

• Always use HTTPS for your webhook endpoints
• Store the webhook secret securely (e.g., in environment variables)
• Process webhooks asynchronously for time-consuming operations
• The webhook timeout is 10 seconds - if your processing takes longer, acknowledge receipt first and then process asynchronously
• Monitor webhook failures in the EventWaivers dashboard

Related

• Setting Up Webhooks
• Webhook Payload Reference
• Troubleshooting and FAQ