Register an endpoint
An owner or administrator registers an HTTPS endpoint allowed by the operator’s exact host policy. The API rechecks current membership, key scope, expiry and consent when saving it. Store the signing secret returned once securely and validate signatures before processing events. A registration timeout needs endpoint-list inspection; creation is not automatically retried.
Disable an endpoint
Use DELETE /api/v1/projects/{project}/webhooks/{id} or sdk.disableWebhook(id). Authorized repeats return the same disabled result. Future enqueue and delivery admission stop; a request already transmitted cannot be recalled. Delivery records follow normal retention; endpoint settings remain until project erasure.
Read retained results
Customer, connection, event, publishing-execution and webhook-delivery pages recheck current access and omit customers being erased. Project settings, usage, billing and webhook destinations also recheck current access before returning data. Mailbox upload and push status check current customer visibility and caller identity. Inbox and mailbox tracker metadata follow the same current-customer rule. Follow nonnull next_cursor or next_sequence even when a scan page is empty. Pages contain at most100 rows, default50. Continue while next_cursor is present, including after an empty page; the cursor advances over scanned records. Individual operation receipts also recheck current access and customer visibility. Scoped Meta ads/inbox receipts and copied events also require a current private snapshot proof. A changed operation read returns409 operation_changed_during_read; retry the status read. An erased receipt is null with provider_data_erased_at set, while its idempotency and outcome record remain. Event pages can be empty while next_cursor advances. New Facebook push registrations and their change events retain the original consent grant; matching deletion requests stop local routing and remove those attributable records in bounded steps. Facebook publishing results and terminal execution events retain their original collection grant. A deletion cutoff hides old result snapshots; cleanup clears provider-returned IDs, URLs and recovery state with provider_data_erased_at, retaining execution status and customer-authored input. Direct authenticated database reads have the same cutoff. An erased execution cannot republish after reconnect. Historical unknown grants are not inferred from a reconnect. This scoped cleanup does not certify complete Meta deletion; the public deletion receiver remains disabled pending full qualification. Retained receipts describe observed outcomes and do not guarantee delivery or complete history.
Make consumers idempotent
Record event identifiers and handle repeated deliveries safely. Webhooks use a durable outbox with bounded attempts and delivery records. Before sending, the Worker checks exact current event content and customer identity, endpoint/signing configuration and lease runway. Invalid or changed snapshots are withheld; event snapshots are limited to64KiB. A change after successful admission or an already transmitted request cannot be recalled. A repeated event should not trigger a duplicate customer action.
Inspect failures
Open Developer tools → Webhooks and filter the delivery log by status, destination UUID or event UUID. These filters apply across pages. The API accepts status, endpoint_id and event_id on GET /api/v1/projects/{project}/webhook-deliveries; the SDK listWebhookDeliveries method accepts the same filters. Start at the first page when changing filters. Records show total attempts and the latest outcome, not every attempt. An acknowledged delivery does not prove downstream processing. Failed deliveries require review; manual replay is not available in this release. Never repeat an ambiguous provider action just to recreate its notification.
Respect rate limits
Respect a valid Retry-After response when throttled. The console displays the bounded wait hint and a safe request reference; it never automatically retries mutations. A timeout can mean a write completed without a received response. Inspect the operation outcome before submitting another action.
These guides describe implemented code and operating requirements. Enabled capabilities and permissions may differ. Use the current API specification and your project’s capability view.
OpenAPI specification