Create a subscription
Open Webhooks in the console, add the HTTPS endpoint, select the event types the receiver understands, and save the signing secret somewhere the receiver can read securely. Do not place it in client-side code, source control, logs, or a support request. Some event types require explicit opt-in even when a wildcard is selected. Review the event-type catalog and select those types deliberately when your receiver is ready.
Use separate subscriptions and secrets for production and test receivers. The endpoint should identify the environment clearly and avoid redirects. Keep the receiver small: authenticate the request, persist the event identity and body, enqueue local work, and return a successful response without waiting for printing or another slow dependency.
Verify and deduplicate every request
Verify the HMAC signature against the exact raw request body before parsing or transforming it. Read the PrintHook signature and timestamp headers as documented in the API reference, apply a reasonable timestamp tolerance, and compare signatures in constant time. Reject a request that cannot be verified.
Use webhook-id as the deduplication key. Store it atomically with the receiver's accepted work so a repeated HTTP request cannot apply the same business action twice. PrintHook delivery is at least once: the receiver may accept a request just before the sender loses the response, and a retry or operator replay can follow.
Read delivery history
Open Deliveries to see each attempt, event ID, target host, attempt number, HTTP result, safe failure message, elapsed time, and scheduled retry time. Filter by webhook, event, or lifecycle state. Open an attempt to compare the endpoint and outcome without exposing the receiver's response body or credential-bearing headers; those are not stored in delivery history.
A failed attempt can be transient, such as a timeout or temporary server error, or permanent, such as a removed route or failed signature policy. Correct the receiver before replaying. A successful HTTP status only confirms that the endpoint accepted the request; use your receiver's own event log to confirm downstream work.
Replay a delivery deliberately
An operator or owner can open an attempt and confirm Replay. Replay uses the subscription's current URL and signing secret but keeps the original event identity and body. That is why deduplication by webhook-id is required. An active automatic retry blocks manual replay, repeated clicks are coalesced, and deleted or cross-account subscriptions cannot be replayed.
Replay is useful after fixing a receiver, restoring a dependency, or rotating a secret. It is not a way to create a new event. If your application needs to re-run business logic for an event it already accepted, do that through an explicit internal recovery process instead of deleting the deduplication record.
Troubleshoot failed webhooks
- Signature failure: verify with the raw bytes, the current secret, and the correct header values before JSON decoding.
- Timeout: acknowledge after durable local acceptance and move expensive work to a queue.
- Repeated events: make the
webhook-iduniqueness check transactional. - Unexpected events: review the subscription's selected event types and receiver version.
- No delivery: confirm the subscription is active and inspect the source event in Events.
Include event and delivery IDs when opening a Support request. Do not include the signing secret, authorization headers, or sensitive print data.