Webhooks

A webhook is an address on your server to which BannerMotion sends a signed POST request when something important happens. There are 13 events and all 13 are emitted today. Webhooks are available on the Team, Agency and Enterprise plans.

Create a webhook

1. In Integrations & API, click Add endpoint and enter the URL of your server (only the Owner and Admin members can).
2. Check the Events you want to receive and click Create endpoint.
3. Copy the secret (whsec_…) and click I've saved it. It is only shown once.
4. In the endpoint menu, choose Send test event to check that it arrives. You will receive a signed webhook.test that does not count toward the pause.

You can have up to 10 webhooks per workspace.

Allowed addresses

For security, only public http or https addresses are accepted, without a username or password. Addresses that point to private, local or metadata networks are rejected, and this is checked again when connecting.

What your server receives

Each event arrives as a POST with a JSON body { id, event, createdAt, data }. The id is the event's (evt_…) and is the same across all retries of that delivery.

Verify the signature

We sign with the Standard Webhooks standard (standardwebhooks.com), so any of its libraries works. The signature is v1, and the HMAC-SHA256, in base64, of webhook-id, a dot, webhook-timestamp, a dot and the exact body you receive. The key is the bytes of the base64 that follows whsec_ in your webhook's secret.

1. Take the body as is, before converting it to JSON.
2. Reject the request if webhook-timestamp differs from your clock by more than 5 minutes.
3. Compute the expected signature and compare it in constant time with each v1,… signature in the header.
4. Discard repeated events by their id.

The SDKs ship verifyWebhook / verify_webhook ready to use. Without an SDK, use the code on the right.

Rotate the secret

In the endpoint menu, Rotate secret creates a new one (shown only once). For 24 hours each delivery carries two signatures, the new secret's and the previous one's, so you can switch your server without losing events. Pass both secrets when verifying while the rotation lasts.

Retries and pause

• →Up to 3 attempts per delivery.
• →Waits of 5 and 30 seconds between attempts.
• →Each attempt waits up to 8 seconds for your response.
• →A redirect (3xx) counts as a failure: it is not followed.
• →After 5 consecutive failures, the webhook pauses itself and stops receiving events until you reactivate it.

Deliveries that exhausted their attempts can be retried manually with Retry, under Recent deliveries.