Inspect webhook delivery attempts, replay failed deliveries, and send test events.
Webhook deliveries and replay
COPE delivers webhooks at least once. Your integration should treat every delivery as retryable and idempotent.
Retries
COPE retries the deliveries it sends on its own schedule:
A 2xx response is a successful delivery.
A 5xx response, a redirect, a timeout or a failed connection is retried automatically, with a longer wait before each attempt. Redirects are not followed.
408, 425 and 429 are retried on the same schedule. COPE does not read a Retry-After header: the next attempt follows the schedule whatever it says.
Any other 4xx is final: the delivery is recorded as failed and is not retried.
A delivery is attempted up to 20 times. The wait before each retry doubles from 30 seconds to a cap of one hour: 30 seconds, then 1, 2, 4, 8, 16 and 32 minutes, then one hour before each of the remaining twelve attempts, so the last attempt comes about 13 hours after the first. These are the shortest waits: a delivery held back with its endpoint’s other deliveries waits longer. A delivery whose 20th attempt fails reads abandoned rather than failed, whatever the response, and is not retried again.
Each automatic attempt gives your endpoint 10 seconds to respond, reading the response body included. A response that takes longer is a timeout.
After several failed attempts in a row, 408, 425 and 429 included, the endpoint’s other pending deliveries are held back for a while instead of being sent at once.
An endpoint is disabled automatically once it holds a delivery that failed and was first attempted 72 hours ago or more, and no successful delivery was first attempted after that failure’s first attempt. One delivery’s automatic retries end in about 13 hours, but when many deliveries are queued for a failing endpoint they are spread out, and a delivery still being retried can count. A delivery that ended with a final 4xx, such as a 401 after a secret rotation, counts too. Test events and bulk replay jobs are left out of this on both sides: a failed one does not disable an endpoint, and a successful one does not count as a successful delivery. A single replay records its result on the delivery it replays, so that result counts as the delivery’s, dated by the delivery’s first attempt. Re-enabling an endpoint starts the check again: a delivery first attempted before the endpoint was re-enabled no longer counts, even if it is replayed afterwards and fails. Sending active: true to an endpoint that is already enabled does not restart the check. COPE emails the notice to the endpoint’s notification_email, which PATCH /v1/webhooks/endpoints/{id} can change; the dashboard sets it when it creates the endpoint and does not change it.
Nothing else is retried. A test event and a single replay are sent once, while you wait, and the response carries your endpoint’s answer. A bulk replay job sends each delivery once: several failures in a row from your endpoint end the job, and the deliveries it had not reached are recorded as not sent; a 408, 425 or 429 does not end it. Replay a failed delivery again once your endpoint accepts it.
The delivery log in the dashboard
The webhook details view in the COPE dashboard shows the request each delivery’s latest attempt sent: the four headers COPE sets (Content-Type, X-Cope-Signature, X-Cope-Timestamp and X-Cope-Event-Id) and the whole envelope, with id, type, version, source, created_at, occurred_at, data, and test on a test event. Headers your server also receives that HTTP adds in transit, such as Host, Content-Length and User-Agent, are not shown. The digest in X-Cope-Signature is masked; its t= is shown. Each attempt is stamped and signed when it is sent, so created_at, X-Cope-Timestamp and the signature are the latest attempt’s.The body is shown indented for reading. Copying the request copies the body exactly as it was sent, which is what the signature covers.The request is shown only when COPE can show exactly what was sent. A delivery that was not sent, that was sent before COPE began showing requests, or whose event type has changed its published body since it was sent, shows the event data only, with no headers.
Replay behavior
Deduplicate by the envelope’s id before applying side effects: a retry or a replay repeats it, and the signature covers it. X-Cope-Event-Id carries the same value but is not signed.
Replay one delivery with POST /v1/webhooks/deliveries/{delivery_id}/replay, or every failed delivery to an endpoint in a time window with POST /v1/webhooks/replay-jobs. Both require an Idempotency-Key header; a delivery that is still being sent, or that a replay job holds, is refused with 409.
Bulk replay is represented as a replay job rather than a synchronous loop.
Bulk replay returns no_matching_deliveries when the selected window has no failed deliveries to replay.
Retention
A delivery stays in the delivery log for 30 days after it succeeded or failed for good, which is also how far back you can replay. A delivery that is still being retried is never removed, and neither is one you replayed while its replay is kept. After that, the delivery, its payload and your endpoint’s response are deleted.
Test events
Use test events to verify endpoint reachability, signature verification, and idempotent processing before subscribing to production event traffic. A test event arrives in the same envelope as a production delivery, with "test": true as its last field.
Send a test of any event type
Pick the event type to send, from the endpoint’s page in the dashboard or through the API. Through the API, call POST /v1/webhooks/endpoints/{id}/test-events with an optional body:
{ "event_type": "cart.order.completed" }
event_type is webhook.test or any event type whose sent is true in GET /v1/webhooks/event-types.
No body, a body that is not valid JSON or not a JSON object, and a body whose event_type is absent or null send webhook.test, a short message with no event data. Fields other than event_type are ignored.
An event_type that is neither a string nor null, or that names a type COPE does not send, answers 422 validation_failed naming event_type. Nothing is sent, and it does not count toward the test-event limit.
The 201 response names the type that was sent in event_type, so you can see when a request sent webhook.test instead of the type you meant. A response recorded before this field existed, such as the replay of an earlier request’s Idempotency-Key, does not carry it.
A test is sent whatever event types the endpoint subscribes to.
Test events are limited to about 10 a minute for your business. Past the limit, the answer is 429 rate_limited with Retry-After.
What arrives
A test of an event type arrives exactly as a delivery of that type would: the same type, version and source, signed with your endpoint’s current secret, with an id of its own. Its data is generated example data that matches the type’s published body, with its times set to when the test is sent. Its business.id is your own; every other value, including names, is invented: the buyer, the order, the product and every amount are the examples shown on the event’s page. On types whose body has event_id, it is unique to each test; it is not the envelope id. Object ids (order, payment, product…) are the same on every test of a type; a system that is idempotent on them may treat a repeat as a duplicate, so tell tests apart by the envelope id (X-Cope-Event-Id). No real buyer, order or payment is ever sent in a test event.
The delivery log lists a test event as a test. A test delivery cannot be replayed: replaying one answers 422 test_delivery_not_replayable, and a bulk replay leaves test deliveries out. Send a new test instead.
When an envelope carries "test": true, verify it and acknowledge it with a 2xx, but do not act on it: do not fulfil an order, grant access, book revenue, send an email or update a record. Its ids name nothing in your account other than your business. A production delivery never carries test.