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
Use delivery and execution receipts to distinguish pending, retryable, failed and ambiguous states. Fix credentials or endpoint errors before replaying authorized work.
Respect rate limits
Back off when a429 response is returned. Do not increase concurrency indefinitely or treat a provider timeout as proof that a write was rejected.
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