Banner events

Events linked to banners - Abyssale Webhooks

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.

You can configure the webhook to send this event only for a specific design.

Important Note: This event will not be triggered when a banner is generated synchronously from a REST API call

Payload Example

{
    "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 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:

  "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:

  "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

{
    "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.