Webhook endpoints

Every endpoint registered on this account, newest first. There are at most 10, so the list is not paged. The signing secret is masked (secretHint); it is returned in full only by create and rotate-secret. An endpoint the service switched off after repeated failures reads enabled: false with disabledAt and disabledReason.

Registers an https:// URL to receive job events, and answers 201 with the endpoint.

The response is the only place the signing secret is ever readable (secret). Store it; a lost secret is rotated, not recovered. Every delivery carries ImageStep-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256("<t>.<raw body>", secret): compute it over the raw body, compare in constant time, and reject a t outside your tolerance window.

Omit events, or send [], to receive every job-level event; per-item events are opt-in.

The URL must be on port 443 — the only port deliveries can reach — and resolve to a public address. The address is checked now and again before every delivery attempt, against what the host resolves to then, and redirects are not followed.

Registered and enabled. The one answer that carries secret in the clear.

One endpoint, its secret masked. enabled, disabledAt, disabledReason and consecutiveFailures say whether events are reaching it; the deliveries themselves are GET /api/v1/webhook-endpoints/{id}/deliveries.

The endpoint

Every field is optional; only what you send changes. A new url is checked as on create.

• events: [] goes back to the default subscription, every job-level event.
• enabled: false pauses the endpoint: nothing new is queued for it, and events already queued are closed as FAILED (endpoint disabled) rather than held.
• enabled: true turns it back on and also clears an automatic disable — disabledAt, disabledReason and consecutiveFailures. POST /{id}/test is the cheap way to check the receiver first.

The endpoint as it now is

Deletes the endpoint and answers 204 with no body. Nothing more is delivered to it: events still queued are closed as FAILED (endpoint no longer exists), and its delivery history is no longer readable. To stop deliveries and keep the endpoint, PUT it with enabled: false.

Deleted

Newest first, with the attempt count, the HTTP status your receiver answered and the next scheduled retry. This is where to look when an event did not arrive. A row does not carry the event body — that is the document your receiver was sent, and eventId is what joins the two. Test deliveries are listed too. Records are kept 14 days.

One page of deliveries

Replaces the signing secret and returns the new one in the clear, once (secret). The old secret stops verifying immediately: every attempt from now on — retries of events queued before the rotation included — is signed with the new one. A delivery your receiver refuses in the switch-over is retried on the normal schedule, so a receiver that answers non-2xx to a bad signature and picks up the new secret within minutes loses nothing.

The endpoint, with the new secret in the clear

Posts a synthetic webhook.test event to the endpoint while you wait, signed like any delivery, and answers with the delivery record: status is DELIVERED when your receiver answered 2xx, otherwise FAILED with responseStatus and error.

• One attempt: a failed test is not retried, and does not count towards the automatic disable. A 2xx resets the endpoint's run of failed events without re-enabling it.
• It works on a disabled endpoint — the way to check a receiver before turning it back on.
• The attempt waits up to 5 s to connect and 10 s for the answer, so this call can take that long.

USE THIS WHEN: verifying a new receiver, or checking signature verification. DO NOT USE WHEN: replaying a real event — this one carries no job data.

The attempt was made — read status: an unreachable receiver is a FAILED delivery, not an error