How a webhook works
- Registration. You give the source system an endpoint URL and the list of events you want to receive.
- Event. Something happens in the source system.
- Delivery. The source sends a
POSTrequest to your URL with a JSON body and a signature header. - Acknowledgement. Your receiver checks the signature and answers with a
2xxstatus within a few seconds. Slow work is done afterwards, in a queue. - Retry. If the answer is not
2xx, or no answer comes, the source tries again after increasing delays. After repeated failures it usually disables the endpoint.
| Part | What it is |
|---|---|
| Endpoint URL | The address on your side that receives deliveries |
| Event type | A name such as asset.updated that says what happened |
| Payload | The JSON body: the event, a timestamp and identifiers |
| Secret | A shared key used to sign and verify each delivery |
| Delivery log | The record of attempts, response codes and errors |
Webhook vs API polling
| Polling an API | Webhook | |
|---|---|---|
| Who starts the request | Your system, on a schedule | The source system, when the event happens |
| Delay | Up to one polling interval | Usually seconds |
| Load | Many requests that return nothing new | One request per event |
| Best for | Bulk reconciliation, reports | Reacting to individual changes |
The two work together. A webhook tells you that something changed, and the API gives you the details. Many systems send only identifiers in the payload, so the receiver reads the current state from the API rather than trusting a copy that may already be out of date.
Securing webhooks
- Verify the signature. Most providers sign each delivery with HMAC (RFC 2104, IETF, 1997) using SHA-256 and the shared secret. Compute the same value over the raw body and compare the two in constant time.
- Check the timestamp. Reject deliveries signed more than a few minutes ago, so a captured request cannot be replayed later.
- Use HTTPS for the endpoint.
- Make the handler idempotent. Retries mean the same event can arrive twice. Processing it a second time must not create a second record.
- Rotate the secret when someone with access leaves or a leak is suspected.
- On the sending side, refuse private addresses. A system that delivers to any URL can be pointed at internal services (server-side request forgery), so a careful sender only delivers to hosts on the public internet.
Webhooks in DAM and marketing work
- Website and CMS. When an approved product photo is updated, the web team's receiver clears the CDN cache so product pages show the new file.
- Product information. When a new packshot finishes ingestion, a receiver attaches it to the right SKU in the product information system.
- Approval. When an asset reaches "Approved" in a workflow, a receiver posts to the team's chat channel or starts a translation job.
- Partner activity. When a distributor opens a share link or downloads from it, the CRM records the activity against the account for the sales team.
- Agency uploads. When an upload batch from an agency completes, a quality check starts.
Common mistakes: doing slow work before answering, which causes timeouts, retries and duplicates; parsing the JSON before verifying the signature, which changes the bytes the signature covers; and not noticing an endpoint that the sender has disabled after repeated failures.
Webhooks in Freedam
- Endpoints are registered through the REST API with a token that has the Manage Webhooks ability. Events cover assets (created, updated, deleted, downloaded), collections and the assets added to or removed from them, share links (created, opened or downloaded from), upload batches (completed or failed) and workflow status changes, or
*for all of them. - Each delivery is a signed
POST: an HMAC-SHA256 of the timestamp and the raw body, sent in theX-Freedam-Signature-256andX-Freedam-Timestampheaders. The TypeScript SDK includes a verification function. The secret is shown once and can be rotated. - Your receiver has 30 seconds to answer. A failed delivery is tried up to 5 times, after 10 seconds, 1 minute, 5 minutes and 30 minutes. After 10 failed attempts in a row the endpoint is disabled.
- An endpoint only receives events about items its owner could see through the API, so a webhook cannot reveal assets hidden by access control.
- Deliveries only go to public internet hosts. The URL is checked when the endpoint is saved and again at each delivery, after the host name is resolved.
- Administrators see every endpoint on the Webhooks tab of the API Management page, with a webhook health chart, and can disable, re-enable or delete an endpoint, or reset its failure count.
Details: the webhooks developer page and the webhooks reference in the Freedam docs.
Frequently asked questions
What is the difference between a webhook and an API?
An API answers requests that your system sends. A webhook is a request the other system sends to you when something happens. Integrations usually use both: the webhook announces the change, and an API call fetches the current data.
What is a webhook URL?
It is the address of the receiver you run, for example a route in your own application or in an automation tool. The source system sends its deliveries there. It must be reachable from the internet and should only accept requests with a valid signature.
What happens if my webhook endpoint is down?
The sender retries for a while, then usually disables the endpoint. Events that happen while it is disabled are often not queued, so after an outage, compare your data with the source through its API to catch what you missed.
Related terms
Follow webhook deliveries in the demo
In the demo you are Nordi's administrator. Open the API Management page, create a token with the Manage Webhooks ability, and follow the health of each endpoint on the Webhooks tab.
You enter Nordi’s workspace as an administrator.