Skip to main content

Receiving Webhooks from Dora

Overview

When you configure a webhook URL in your Custom Website integration, Dora will automatically send HTTP POST requests to your endpoint whenever delivery events occur.

Setup

  1. Configure Webhook URL
    • Go to Integrations → Custom Website
    • Enter your webhook endpoint URL (e.g., https://yoursite.com/webhooks/dora)
    • Select which events you want to receive
    • Save the configuration
  2. Implement Webhook Endpoint
    • Create an endpoint on your server to receive POST requests
    • Verify the webhook signature (see below)
    • Process the event data

Webhook Events

Dora sends the following events:

Webhook Payload

json

HTTP Headers

Dora includes the following headers with each webhook request:

Signature Verification

IMPORTANT: Always verify the webhook signature to ensure the request came from Dora. The X-Dora-Signature header contains an HMAC SHA256 hash of the payload using your API key as the secret.

Code Example

php

Retry Logic

If your endpoint returns a non-2xx status code or times out, Dora will retry the webhook:
  • Attempt 1: Immediate
  • Attempt 2: After 1 minute
  • Attempt 3: After 5 minutes
  • Attempt 4: After 15 minutes
After 3 failed attempts, the webhook will be marked as failed.

Best Practices

  1. Respond Quickly
    • Return a 200 status code immediately
    • Process the event asynchronously (queue it)
    • Don’t perform long-running operations in the webhook handler
  2. Verify Signatures
    • Always verify the X-Dora-Signature header
    • Use constant-time comparison to prevent timing attacks
  3. Handle Duplicates
    • Webhooks may be sent multiple times
    • Use delivery_id to detect and ignore duplicates
  4. Monitor Failures
    • Log all webhook requests
    • Set up alerts for repeated failures
    • Check the webhook events log in Dora dashboard
  5. Use HTTPS
    • Always use HTTPS for your webhook endpoint
    • Dora will not send webhooks to HTTP URLs

Testing Webhooks

You can test your webhook endpoint using tools like:
  • ngrok: Expose your local server to the internet
  • RequestBin: Inspect webhook payloads
  • Postman: Manually send test requests
Example test payload:

Troubleshooting

Webhooks not being received?
  • Check that your URL is publicly accessible
  • Verify your server is running and responding
  • Check firewall rules
  • Review server logs for errors
Signature verification failing?
  • Ensure you’re using the correct API key
  • Verify you’re hashing the raw request body
  • Check for encoding issues
Need help?