# Banner events This page details the webhook events linked to the generation and creation of banners/visuals within your workspace. ### NEW\_BANNER This event is triggered when a single banner has been successfully generated or saved within the Abyssale application, or asynchronously generated via the API. {% hint style="info" %} You can configure the webhook to send this event only for a specific design. {% endhint %} {% hint style="warning" %} Important Note: This event will not be triggered when a banner is generated **synchronously** from a REST API call {% endhint %} #### Payload Example ```json { "id": "a14e1d26-ff41-47cb-bbf9-8f2d777a5bd7", "version": 1, "sharing_id": "5fcec999-2bfb-4dd7-ba38-2d9e16c49149", "file": { "type": "jpeg", "url": "url/name.jpeg", "cdn_url": "cdn_url/name.jpeg", "filename": "name.jpeg" }, "format": { "id": "300x250-medium-rectangle", "width": 300, "height": 250 }, "template": { "id": "873608a1-e498-47dd-a36d-bd065e3e2b8e", "name": "Template name", "created_at": 1623229458, "updated_at": 1623229457 } } ``` #### Payload Field Definitions | `id` | `string` (UUID v4) | The ID of the initial asynchronous generation request you received when calling the API. | | --------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | `number` | The version number of this specific visual. If a visual is updated or re-generated, the `sharing_id` remains the same, but the `version` number increments. | | `sharing_id` | `string` (UUID v4) | The identifier for the parent visual that this visual originated from. All versions of the same visual share this common ID, which is also used to construct the view link. | | `file.type` | `string` | The file format of the generated banner (e.g., `jpeg`, `png`, `pdf`). | | `file.url` | `string` | The direct URL where the image is stored. | | `file.cdn_url` | `string` | The CDN URL for high-speed, low-latency performance. *Note: A limited bandwidth applies to CDN URLs across all plans. Please check the* [*pricing table*](https://www.abyssale.com/pricing) *for details.* | | `file.filename` | `string` | The name of the resulting file. *If the related design contains a custom naming scheme, this property reflects the custom name.* | | `format.id` | `string` | The unique name/ID of the format as defined in the template (e.g., `300x250-medium-rectangle`). | | `format.width` | `number` | The width of the format in its original unit of measure. | | `format.height` | `number` | The height of the format in its original unit of measure. | | `template.id` | `string` (UUID v4) | The unique ID of the template used to generate the banner. | | `template.name` | `string` | The template name as defined in the application. | | `template.created_at` | `number` (Timestamp) | Template creation date (Unix timestamp format). | | `template.updated_at` | `number` (Timestamp) | Template updated date (Unix timestamp format). | #### Optional Properties: Visual URL Properties When a visual is saved or generated, the API response includes specific URLs to access the visual's details and, optionally, its edit interface. 1\. `view_url` **This property provides the direct link to view the final, saved visual and its associated details within the application interface.** * *Type*: String (URL) * *Description*: A **private URL** to the details page of the saved visual. This URL is used for viewing the visual's properties, downloading it, and accessing other associated actions. * *Condition*: Always returned when a visual is successfully generated via the frontend/client-side application. > 📝 Note on API Generation: If the visual is generated via the API, the `view_url` is only returned if the global account setting "Store a copy of visuals generated via API" is toggled on. If this setting is off, the visual is considered transient, and no `view_url` will be provided. * *Format Example*: ```json "view_url": "https://app.abyssale.com/designs/{design_id}/visual/{visual_id}/details" ``` *** 2\. `edit_url` This property provides a deep link directly to the visual editing interface, allowing for further modification of the generated visual. * *Type*: String (URL) * *Description*: A URL that opens the visual in the application's editor. This is crucial for workflows that require post-generation adjustments. * *Condition*: **Only returned when the visual has been generated from a static design.** It is not returned if the visual was created from a dynamic source where re-editing is not supported. * *Format Example*: ```json "edit_url": "https://app.abyssale.com/visual/{visual_id}/edit" ``` #### 💡 Key Distinction | **Property** | **Purpose** | **Availability** | | ------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------- | | `view_url` | Viewing the final, saved asset and its details. | Always available on a saved visual. | | `edit_url` | Modifying the asset in the editor. | Only available if the asset was generated from a *static design* and can be re-edited. | ### NEW\_BANNER\_BATCH This event is triggered when an asynchronous batch visual generation API request has completed its processing, whether successful or containing errors. * Filterable by Design: Yes. * Purpose: This is the notification you receive when you initiate a batch generation job that creates multiple banners. #### Payload Example ```json { "generation_request_id": "c18c3cec-14c2-4539-99d4-92623b6a4aef", "banners": [ { "id": "ec3a9fcd-f209-4077-b5ea-037d4bdfa9f2", "file": { "type": "jpeg", "url": "url/name.jpeg", "cdn_url": "cdn_url/name.jpeg", "filename": "name.jpeg" }, "format": { "id": "facebook", "width": 1200, "height": 628 }, "template": { "id": "834362df-966b-46fb-a92b-213f3c2ceeac", "name": "Template name", "created_at": 1649682431, "updated_at": 1649682494 } } ], "errors":[ { template_format_name: "(Placeholder Format, will be the real value)", reason: "Element text_placeholder error: The text 'Placeholder text' cannot fit within the defined space.", } ] } ``` #### Payload Field Definitions | `generation_request_id` | `string` (UUID v4) | The ID of the initial asynchronous generation request you received when calling the API. | | ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `banners` | `array` | A list of banner objects that were successfully created. The properties are identical to the data found in the `NEW_BANNER` event. | | `errors` | `array` | A list of objects detailing any generation errors, including the format name and the reason for failure. |