API

Webhook events

The 13 events, all emitted today: when they fire, what the data field carries and an example of each.

BannerMotion notifies your server with a signed POST request every time something important happens: a concept is ready, a review is approved, an export is finished. All 13 events are emitted today: subscribe to the ones you want.

The envelope of every event

The body is always JSON with id (the event's), event, createdAt and data. The headers and the signature are on the Webhooks page.

{
  "id": "evt_p0q8w2e6r4t1",
  "event": "banner.generated",
  "createdAt": "2026-01-01T12:00:00.000Z",
  "data": {
    "jobId": "job_x4k2m9q1a7bz",
    "campaignId": "cmp_8f2a1c3d4e5f",
    "creativeId": "crt_3a9c0d1e2f4b",
    "versionNo": 1,
    "source": "api"
  }
}

Generation

EventWhenFields in data

banner.generated

A concept finished generating, with all its sizes and locales. Generations made through the API and in the app both emit it.

jobId, campaignId, creativeId, versionNo?, source

banner.updated

A correction or the addition of sizes (made through the API) finished and saved a new version. change is edit or sizes.

jobId, creativeId, change, versionNo, source

generation.failed

A generation, a correction or an addition of sizes failed. The credits are returned.

jobId, campaignId?, creativeId?, change?, error

translation.completed

The translation of a banner finished after adding a locale to a campaign through the API. One event arrives per banner.

jobId, campaignId, creativeId, locale, translated, pending, source

Review and approval

EventWhenFields in data

review.requested

Someone sent a campaign for review. pieces is how many pieces went into review.

campaignId, pieces, toRoles

review.commented

Someone commented on a piece in a review.

campaignId, pieceId, commentId

review.approved

Pieces were approved. by is member (someone on the team) or link (the client, from their link).

campaignId, pieceIds, by, author

review.changes_requested

Changes were requested on pieces. by is member or link.

campaignId, pieceIds, by, author

Export

EventWhenFields in data

export.ready

An export is ready to download. status is ready or warnings; artifactSha256 is the .zip's sha-256.

exportId, creativeId, status, bytes, artifactSha256

export.failed

An export failed and no piece could be built.

exportId, creativeId, message

Team and usage

EventWhenFields in data

member.invited

A person was invited to the workspace.

email, role

member.joined

A person joined the workspace by accepting an invitation (via: invite). The value via: sso is reserved for single sign-on, which is not available yet.

userId, email, role, via

usage.threshold_reached

The credit balance fell below 20% of the plan's allowance. It is announced only once a month per workspace.

balance, planCredits, percentUsed

Nota. Fields marked with ? do not always arrive: banner.generated carries no versionNo when the concept was generated from the app, and generation.failed carries campaignId when creating and creativeId and change when correcting or adding sizes.

The test event

webhook.test is the one Send test event sends. Test event sent by "Send test event" in the app. It does not count toward the automatic pause. Its data is { "message", "workspace" }.

WebhooksReceive signed notices on your server: how to create the endpoint, verify the signature and handle retries.Job statusCheck a generation job or follow it live with SSE events.

Esta página foi útil?