Webhooks

Webhooks let your systems react to what happens in freedam instead of constantly asking. When an asset finishes uploading, a share is created, or a big job completes, freedam notifies a web address you choose 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.

What it does

You register one or more addresses and choose which events each one should hear about. Events cover the library's main moments:

• Assets - created, updated, deleted, restored
• Collections - created, updated, deleted
• Shares - created, revoked
• Pipelines - an upload batch finishing, or a background job completing
• Testing - a practice event you can trigger on demand to check your setup

Each notification carries the event type, when it happened, and the details of the asset, collection, or share involved.

How it works

You set up endpoints in the admin area under API → Webhooks (or through the API). Each endpoint gets a signing secret, shown once - your system uses it to confirm that incoming notifications genuinely came from your freedam instance and are not forged or replayed. If you use the TypeScript SDK, that verification is a single call.

Delivery is built to be dependable. If your system is briefly down or slow to answer, freedam retries the notification several times over the following hours, spacing the attempts out. If an endpoint keeps failing, it is switched off automatically rather than hammered forever.

And when something goes wrong, you do not have to dig through server logs. Every endpoint keeps a delivery history - each recent attempt with its outcome, how long it took, and what your server answered - visible in the admin UI. You can also send a test event at any time to check a new setup before real traffic hits it.

Good to know

• Endpoints must use HTTPS and answer quickly - acknowledge first, do the heavy work afterwards.
• Secrets rotate cleanly. You can issue a new signing secret at any moment, and the old one stops working 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.
• Managing webhooks through the API uses the same tokens and permissions as everything else.

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