Webhook Security

Every webhook delivery includes an X-Signature header containing an HMAC-SHA256 hash of the request body, signed with your webhook's signing secret.

Verification Steps

1. Extract the X-Signature header from the incoming request
2. Compute the HMAC-SHA256 hash of the raw request body using your signing secret
3. Compare the computed hash with the received signature using a timing-safe comparison

Code Examples

import hmac
import hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
# body = request.get_data()
# signature = request.headers.get('X-Signature')
# is_valid = verify_webhook(body, signature, 'whsec_your_secret')

Event Payload Examples

export.created

{
  "event": "export.created",
  "status": "processing",
  "platform": "youtube",
  "message_id": "msg_abc123"
}

export.finished

{
  "event": "export.finished",
  "status": "done",
  "comments_count": 150,
  "download_url": "https://exportcomments.com/exports/12345.xlsx"
}

export.failed

{
  "event": "export.failed",
  "status": "failed",
  "error_message": "Video not found or is private"
}

Best Practices

1. Always verify signatures using hash_equals() or timing-safe comparison to prevent timing attacks
2. Use message_id for idempotency to avoid processing duplicate deliveries
3. Return 200 immediately and process the webhook payload asynchronously
4. Auto-suspension: Webhooks are suspended after 30 consecutive delivery failures. Re-enable via the toggle endpoint after fixing your endpoint