Connecting freedam to your systems through webhooks means you stop polling and start reacting. When an asset finishes ingesting, a share is created, or a bulk operation completes, freedam sends an HTTP POST to a URL you control within seconds — so your CMS can pick up the new hero image, your Slack bot can announce the campaign folder, or your pipeline can kick off the next step, without anyone refreshing a page or burning API budget on "anything new yet?" requests.

What it does

You register one or more HTTPS endpoints and choose which events each one should receive. Events cover the library's main lifecycle moments:

• Assets — asset.created, asset.updated, asset.deleted, asset.restored
• Collections — collection.created, collection.updated, collection.deleted
• Shares — share.created, share.revoked
• Pipelines — upload.batch.completed when an ingestion batch finishes, operation.completed when an async operation reaches a terminal state
• Testing — webhook.test, a synthetic event you can trigger on demand to verify your handler

Each delivery is a JSON payload with a unique event id, the event type, a timestamp, and the relevant resource data — assets are identified by their public GAID.

How it works

Register an endpoint with POST /v1/webhooks (or manage endpoints in the admin UI under API → Webhooks). The response includes a signing secret, shown exactly once — store it server-side.

Every delivery is signed with HMAC-SHA256 over the timestamp and the raw request body, sent in a signature header alongside the event type and a delivery UUID. Your handler recomputes the HMAC with the shared secret, compares in constant time, and rejects anything with a stale timestamp (older than five minutes) to shut out replay attacks. If you use the TypeScript SDK, verifyWebhookSignature does all of this for you.

Your endpoint acknowledges with a 2xx response within 10 seconds. Anything else counts as a failure, and failed deliveries are retried with exponential back-off: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After repeated failures the endpoint is automatically disabled rather than hammered forever.

When something goes wrong, you do not have to grep production logs. GET /v1/webhooks/{id}/deliveries returns the most recent attempts with status code, latency, and a response excerpt — the same history is visible in the admin UI. A POST /v1/webhooks/{id}/test sends a synthetic event so you can validate a handler before real traffic hits it.

Good to know

• Endpoints must be HTTPS and respond within the 10-second window — do heavy processing asynchronously after acknowledging.
• Secrets rotate cleanly: POST /v1/webhooks/{id}/rotate-secret issues a new signing secret, and old signatures stop verifying immediately. Rotate when a teammate leaves or after a suspected leak.
• You can pause without deleting: set an endpoint inactive to silence it while keeping its configuration.
• Webhook management requires an API token with the appropriate scopes, like the rest of the v1 API, and management calls count against the standard per-token rate limit.

The full delivery contract — headers, payload shapes, and verification examples — is in the API documentation. Curious how it feels end to end? Try the demo.