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.
Open your organisation settings and go to the Developer section.
Under Webhooks, select CREATE WEBHOOK.
Enter the Webhook URL, the endpoint that will receive the POST. It must use HTTPS.
Add a Description to say what the endpoint is for.
Under Events, choose one or more events from the drop-down list.
Save the webhook. It appears in the Webhooks table.
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 |
2. Build the signed string | Join the timestamp, a |
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 |
5. Check the timestamp | Reject the delivery if |
📕 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 |
|
Timestamp |
|
Body |
|
Expected signature |
|
✅ 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 |
Redirects | Redirects ( |
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 |
Out-of-order deliveries | Events are not guaranteed to arrive in order. Compare |
Edited assets | Editing an asset sends a new event with a new |
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 |
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 |
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. |



