# 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. | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.abyssale.com/webhooks/events/banner-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.