# Overview - Webhooks

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](https://help.abyssale.com/en/articles/92373-create-abyssale-webhook)

Once configured, review the [Events Reference](https://developers.abyssale.com/webhooks/events) page to understand the structure of the JSON payloads you will receive for each event type.