Webhooks and Callbacks

Callbacks are durable deliveries created when an Action with a callback_url reaches a terminal state. They are queued with the terminal event; a callback failure never changes the Action outcome.

Signature headers

• X-Actionbox-Event
• X-Actionbox-Timestamp — Unix seconds
• X-Actionbox-Signature — v1=<hex HMAC-SHA256>

Compute HMAC-SHA256 over "{timestamp}." + raw_request_body using the per-Source webhook secret returned when the Source is created or its secret is rotated.

import hashlib
import hmac

def verify(timestamp: str, raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    expected = hmac.new(
        webhook_secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(signature, f"v1={expected}")

Reject stale timestamps according to your replay window, use a constant-time comparison, and deduplicate the event id from the JSON body. Parse JSON only after verifying the exact raw bytes.

Delivery behavior

• HTTP 2xx marks the delivery delivered.
• Network errors, timeouts, HTTP 429, and HTTP 5xx are retried on the bounded server schedule.
• Other non-2xx responses fail permanently.
• A valid Retry-After may delay the next retry.
• Consumers must be idempotent because delivery is at least once.

Hosted callback URLs must use public HTTPS, cannot contain credentials, are revalidated before delivery, and do not follow redirects. Keep the webhook secret out of URLs and logs.