Skip to main content

Webhooks

Written by Yoanna Hristova

Webhooks send an HTTP POST to your own endpoint automatically when selected events happen in Grabyo. Downstream workflows can start as soon as content is created, without polling the API for new clips, GIFs or images.

Each webhook keeps a delivery history, so you can see what was sent, check whether it succeeded, and replay a delivery while testing or troubleshooting.

📕 Note: Webhooks are available to all customers with API access. See API Access to get it enabled.

Why use webhooks?

Benefit

Details

No more polling

Grabyo notifies your system when content is created, so there is no need to keep checking the API for new clips and related assets.

Near real-time triggers

Workflows start as soon as the event happens.

Delivery visibility

Every delivery attempt is listed with its outcome.

Replay

Send a previous POST again when validating setup or recovering from an issue on the receiving side.

Supported events

A webhook can subscribe to one or more events. Three content creation events are currently supported.

Event

Sent when

Use it for

Clip created

A new clip is created

Starting workflows tied to clip creation

GIF created

A new GIF is created

Automating GIF-based content pipelines

Image created

A new image is created

Automating image creation workflows

How to create a webhook

Webhooks are created and managed in the Developer section of your organisation settings, below the API keys table.

📕 Note: the Developer section was previously named API. It has been renamed to cover broader developer tooling.

  1. Open your organisation settings and go to the Developer section.

  2. Under Webhooks, select CREATE WEBHOOK.

  3. Enter the Webhook URL, the endpoint that will receive the POST. It must use HTTPS.

  4. Add a Description to say what the endpoint is for.

  5. Under Events, choose one or more events from the drop-down list.

  6. Save the webhook. It appears in the Webhooks table.

  7. Copy the signing secret that is shown and store it securely. You need it to verify deliveries.

📕 Note: The signing secret is shown only once it can't be shown again, and Grabyo can't retrieve it for you. Treat it like a password. Keep it in a secrets manager or similar, and never commit it to code, write it to logs or include it in a support ticket. If you lose it, delete the webhook and create a new one.

Managing webhooks

The Webhooks table lists every webhook in the organisation with its description, URL, subscribed events and status. A webhook is either Active or Inactive.

Select the options menu at the end of a webhook’s row to see the available actions.

Action

Use it to

Disable

Disable the webhook.

Deliveries

Open the delivery history for the webhook.

Delete webhook

Delete the webhook.

📕 Note: A webhook can become Inactive automatically if deliveries to it keep failing. Fix your endpoint, replay a delivery to check it now works, then re-enable the webhook.

Example POST

When a subscribed event occurs, Grabyo sends an HTTP POST to the webhook URL. This is the body sent when a clip is created.

{   "id": "String",
"type": "clip.created",
"version": "1",
"publishedAt": "2026-09-07T09:42:10.211Z",
"data": {
"assetId": "String",
"campaignId": "String",
"streamId": "String",
"title": "example title",
"description": "example description",
"mediaUrl": "String",
"thumbnailUrl": "String",
"createdAt": "2026-09-07T09:41:35.221Z"
}
}

mediaUrl and thumbnailUrl are download URLs for the asset and its thumbnail.

Media links expire after 24 hours: mediaUrl and thumbnailUrl are presigned for 24 hours from when the event happened. Download what you need when the event arrives. Do not store the link and expect it to work later. Retries and replays carry the same links with the same expiry, so a delivery replayed more than a day after the event will have links that no longer work.

Verifying deliveries

Your webhook URL is public, so anyone who learns it can send it a request that looks like one from Grabyo. Every delivery is signed with your webhook's signing secret, so you can check that a request really came from Grabyo before acting on it. Verify the signature on every delivery.

Every delivery includes a Grabyo-Signature header, for example:

Grabyo-Signature: t=1787563804,v1=ad30aa27cbce97dd3c7109a25c8d24c6840f273aca11abcbc439cc96816a7e45

Step

What to do

1. Read the header

Split on , and then on =. t is the timestamp and v1 is the signature. Ignore anything else. Reject the delivery if either value is missing or t is not a whole number.

2. Build the signed string

Join the timestamp, a . and the raw request body, for example 1787563804.{"id":"abc",...}

3. Compute the signature

Calculate the HMAC-SHA256 of that string, using your webhook's signing secret as the key, and encode it as hex.

4. Compare

Compare your result with v1 using a constant-time comparison, for example hmac.compare_digest in Python, crypto.timingSafeEqual in Node or hmac.Equal in Go. Don't use a plain ==.

5. Check the timestamp

Reject the delivery if t is more than five minutes old. This stops an intercepted delivery from being sent again later.

📕 Note: Most failed verifications happen because the parsed and re-serialised JSON was hashed instead of the raw body. Re-serialising changes key order and whitespace, so the signature never matches. Hash the exact bytes you received, before any JSON parsing.

Testing your verification

Check your code against these values. A correct implementation produces the expected signature.

Input

Value

Secret

whsec_test_secret

Timestamp

1787563804

Body

{"id":"abc","type":"clip.created"}

Expected signature

ad30aa27cbce97dd3c7109a25c8d24c6840f273aca11abcbc439cc96816a7e45

✅ Tip: A full verification of this example still fails the five-minute timestamp check, because the timestamp is old. That is expected.

Endpoint requirements and retries

Your endpoint needs to meet these requirements for a delivery to count as successful.

Requirement

Details

HTTPS

The webhook URL must use HTTPS.

Response

Return a 2xx status code within 10 seconds. Anything else counts as a failure, including a timeout or a 4xx or 5xx response.

Redirects

Redirects (3xx) are not followed and count as a failure.

Replay window

A failed delivery can be replayed from the delivery history for 7 days. After that the record is deleted and the event can't be sent again.

✅ Tip: If your processing takes a while, return a 2xx straight away and process the event afterwards. That keeps you inside the 10-second limit.

📕 Note: Each delivery attempt has its own Grabyo-Delivery-Id header. Include it when you contact Support about a delivery so we can find that attempt quickly.

Duplicate and out-of-order deliveries

Webhooks are delivered at least once, so the same event can sometimes arrive more than once or out of order.

Situation

How to handle it

Duplicate deliveries

The body's id identifies the event and stays the same across retries and replays. Ignore any id you have already processed.

Out-of-order deliveries

Events are not guaranteed to arrive in order. Compare publishedAt before applying an update.

Edited assets

Editing an asset sends a new event with a new id and the same data.assetId. This is not a duplicate.

Delivery history and replay

Every POST sent to a webhook is recorded in its delivery history. To open it, select Deliveries from the webhooks options menu.

Delivery details

Open a single delivery to see what happened.

Section

What it shows

Outcome

Delivery details, including the status and how long the delivery took.

Request and response

The request and response, including headers and body.

📕 Note: Delivery details can contain sensitive information. Remove or hide it before sharing screenshots of a delivery.

Replaying a delivery

A previously sent POST can be sent again with REPLAY, shown next to the delivery in the history.

✅ Tip: Use replay to validate endpoint setup, retest a fix, or recover from a temporary issue on the receiving side, without waiting for a new event to occur.

Troubleshooting

Situation

What to check

What to do

No events are arriving

The webhook exists, the correct events are selected, its status is Active, and the destination endpoint is reachable.

Confirm the selected event type, trigger a fresh event, then review the delivery history.

Intermittent failures

Delivery results, timing, response details and how the receiving endpoint behaves.

Use the delivery history to find the failure pattern. Replay after updating the endpoint.

Testing initial setup

The delivery history, and that the POST is received on your side.

Create a test clip, GIF or image and review the resulting POST in the delivery history.

The signature never matches

Whether you are hashing the raw request body or re-serialised JSON, and whether you are using the secret for the right webhook.

Hash the exact bytes received, before any JSON parsing. In Express, for example, use express.raw() on the webhook route. Then check your code against the test values in Verifying deliveries.

Verification works locally but fails in production

The clock on your production server.

If the clock is more than five minutes out, every delivery fails the timestamp check. Sync it with NTP.

Your server shows success, but the delivery history shows failures

The delivery duration in the delivery details.

Your endpoint is taking longer than 10 seconds to respond. Return a 2xx first and process the event afterwards.

The webhook is Inactive and you didn't disable it

Recent deliveries in the history, looking for repeated rejections or no response.

It was probably disabled automatically. Fix the endpoint, replay a delivery to check it, then re-enable the webhook.

You've lost your signing secret

Nothing to check: the secret can't be retrieved.

Delete the webhook and create a new one, then store the new secret securely.

Did this answer your question?