Banner Events

This page details the webhook events linked to the generation and creation of banners within your workspace.

NEW_BANNER

Triggered when a single banner has been successfully generated or saved — either from within the Abyssale application or asynchronously via the API.

INFO

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

WARNING

This event is not 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": 1649942114
  }
}

Payload Field Definitions

Field	Type	Description
id	UUID v4	Unique ID of the generated banner.
version	number	Version number of the visual. Increments on re-generation; sharing_id stays the same.
sharing_id	UUID v4	Identifier shared across all versions of the same visual.
file.type	string	File format: jpeg, png, pdf, etc.
file.url	string	Direct storage URL.
file.cdn_url	string	CDN URL for low-latency delivery. Bandwidth limits apply per plan.
file.filename	string	Resulting filename (reflects custom naming scheme if configured).
format.id	string	Format name/ID as defined in the template.
format.width	number	Width in the format's unit of measure.
format.height	number	Height in the format's unit of measure.
template.id	UUID v4	ID of the template used.
template.name	string	Template name.
template.created_at	Unix timestamp	Template creation date.
template.updated_at	Unix timestamp	Template last-updated date.

Optional URL Properties

Property	Description	Condition
view_url	Link to the visual's detail page in the app.	Always returned for frontend-generated visuals. For API generation, only if "Store a copy of visuals generated via API" is enabled.
edit_url	Deep link to the visual editor.	Only returned when the visual was generated from a static design.

---

NEW_BANNER_BATCH

Triggered when an asynchronous batch generation API request has completed, whether successful or with errors.

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": "some-format",
      "reason": "Element text_placeholder error: The text 'Placeholder text' cannot fit within the defined space."
    }
  ]
}

Payload Field Definitions

Field	Type	Description
generation_request_id	UUID v4	ID of the initial async generation request.
banners	array	Successfully created banners. Same properties as NEW_BANNER.
errors	array	Generation errors with template_format_name and reason.

Related

• Webhooks Overview — how to configure webhook endpoints
• Asynchronous Generation — the generation requests that trigger these events
• Global Events — export completion events