Developer Center›Guides›Webhooks

    Webhooks

    Use the public `/api/v1/webhooks` routes to create endpoints, inspect delivery history, test endpoint reachability, replay deliveries, and rotate secrets.

    Public Routes

    • GET /api/v1/webhooks lists webhooks and recent deliveries.
    • POST /api/v1/webhooks creates a webhook with url, events, and optional enabled.
    • GET /api/v1/webhooks/{id} returns one webhook plus delivery history.
    • PATCH /api/v1/webhooks/{id} updates URL, events, enabled state, and can rotate the secret with rotate_secret: true.
    • DELETE /api/v1/webhooks/{id} removes a webhook.

    Delivery Operations

    • GET /api/v1/webhooks/{id}/deliveries returns recent delivery attempts.
    • POST /api/v1/webhooks/{id}/test queues a test delivery using one of the supported event names.
    • POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay replays a stored delivery payload.

    Event Names

    file.generated
    transmission.success
    transmission.failed
    dispute.created
    dispute.resolved
    record.updated
    record.created
    record.deleted

    Delivery Format

    • Payload body: { event, timestamp, data }
    • Signature header: X-Webhook-Signature
    • Event header: X-Webhook-Event
    • Delivery ID header: X-Webhook-Delivery
    • Retries: immediate, then roughly 30 seconds, then roughly 2 minutes.

    Operational Notes

    • Deliveries are HMAC-SHA256 signed with the webhook's current secret.
    • Replay creates a new delivery attempt record; it does not mutate the original delivery row.
    • Retries occur immediately, then after roughly 30 seconds, then after roughly 2 minutes.