Overview - Webhooks

Use webhooks to get events (new banners, design status changes etc..) from Abyssale.

Abyssale sends you notifications when new events happen on your Abyssale account.

Webhooks are a powerful tool for integrating Abyssale into your custom workflows, allowing for near real-time automation and updates. They represent a significant efficiency improvement over traditional polling methods (where your server constantly asks Abyssale for updates).

What are webhooks ?

A webhook is an automated way for Abyssale to send data to your application as soon as a specific event occurs within your Abyssale workspace.

Essentially, when an event you subscribe to takes place (e.g., a new banner is generated, a design status changes), Abyssale acts as the sender and pushes an HTTP POST request to a unique URL you define, called the Endpoint. The request body contains a JSON payload with all the relevant event data.

Why Use Webhooks?

Webhooks enable immediate action and remove the need for your application to repeatedly check (or "poll") our API for changes. This saves resources and ensures your system is always up-to-date.

🎯 Example of Use Cases

Here are a few examples of common automation workflows enabled by Abyssale Webhooks:

1. Instant Asset Delivery: When a new banner is created (the NEW_BANNER event), you instantly receive the public download URL. Your system can immediately grab the image file and upload it to your own CDN, S3 bucket, or media library.

2. Export Completion & Distribution (NEW_EXPORT): Once a design export process is finished, the API sends you a notification with the URL to the resulting ZIP file. Your backend can receive this event, download the ZIP file, and automatically push a notification (e.g., to Slack) containing the download link for easy team distribution.

3. Workflow Synchronization (TEMPLATE_STATUS): Notify your internal tools (like Slack or a project management board) when a design's status changes. This is particularly useful for closing out a creative cycle: automatically notify stakeholders when a design is marked as APPROVED or, conversely, when it is REJECTED by a manager or client, providing immediate feedback for the next step.

4. Asynchronous Completion: When you initiate a batch generation job via the API, the NEW_BANNER_BATCH event lets you know the exact moment the entire batch is complete, triggering a client notification or fulfillment workflow.

Technical Mechanism

All webhooks from Abyssale follow a consistent delivery mechanism:

Property	Detail
Method	HTTP POST (Sent over HTTPS)
Content Type	application/json
Endpoint	A public URL on your server that is set up to listen for and process incoming JSON data.
Acknowledgement	Your endpoint must return an HTTP 200 OK response within a short timeframe (max 15 seconds) to acknowledge successful receipt of the payload.
Delivery & Retries	To ensure reliability, Abyssale utilizes a retry mechanism. If your endpoint fails to respond with an HTTP 200 OK (e.g., due to a timeout, HTTP 500 error, or connection issue), Abyssale will queue the notification and attempt redelivery (5 times maximum in a 3-hours window). This ensures that you don't miss critical events.
Static IP Support	Abyssale uses a static range of server IP addresses for webhook deliveries. If your service requires IP whitelisting, please contact our support team for the current list of IP ranges.
Identifying Header	The request includes the X-Referer: api.abyssale.com header, allowing you to easily identify Abyssale webhook requests.

Getting Started

To begin receiving event notifications, you need to configure your webhook settings in the Abyssale application dashboard.

For step-by-step instructions on setting up your endpoint and subscribing to events, please refer to our help center guide:

How to Create an Abyssale Webhook

Once configured, review the Events Reference page to understand the structure of the JSON payloads you will receive for each event type.