Overview — Webhooks
When an event you subscribe to happens, Abyssale sends an HTTP POST with a JSON payload to a URL you control — so you learn about a finished render without polling for it.
Start by creating a webhook in the dashboard, then pick your payloads from the Events reference.
What your endpoint must do
| Property | Detail |
|---|---|
| Method | HTTP POST (HTTPS only) |
| Content type | application/json |
| Endpoint | A public URL on your server |
| Acknowledgement | Return 200 or 201 within 15 seconds |
| Retries | The first attempt, then up to 6 retries — about 3 hours in total |
| Backoff | 15 s, 15 s, 3 min, 10 min, 30 min, 2 h |
| Identifying header | X-Referer: api.abyssale.com |
| Static IP support | Contact support for IP whitelisting ranges |
Anything other than 200/201 counts as a failure and is retried. The 15 seconds is a hard timeout, so acknowledge first and do your work afterwards.
Answer 410 to stop the retries
410 Gone is the one response that is never retried — it is how a receiver says an endpoint is retired. Every other failure keeps its place in the backoff schedule above.
Requests are not signed
There is no signature header and no shared secret, so the payload alone does not prove the request came from Abyssale — treat X-Referer as a hint, not as authentication. Use an unguessable callback path, and verify anything that matters against the API (GET /generation-request/{id}, GET /banners/{id}) before acting on it.
Build your receiver to be idempotent. A retry re-sends the same payload, and a webhook is not ordered against your own polling — you may see a job finish through the status endpoint first. Treat a payload as "this is ready", keyed on its id, rather than as a one-shot event you cannot afford to miss.
Every payload names its event
Every webhook payload carries a top-level event_type field ("NEW_BANNER", "NEW_BANNER_BATCH", "NEW_EXPORT", "TEMPLATE_STATUS", …) — route on it instead of inferring the event from the payload structure. Job-specific callback_url deliveries carry it too.
What people use them for
| Event | Typical use |
|---|---|
NEW_BANNER | Take the download URL and push the asset to your own CDN or S3 bucket |
NEW_BANNER_BATCH | Know the exact moment an async batch finishes |
NEW_EXPORT | Download the ZIP and notify your team |
TEMPLATE_STATUS | Tell internal tools when a design is approved or rejected |