Webhooks
Webhooks deliver lifecycle events to external HTTP endpoints. Admins register endpoints in AdminCP → Setup → Webhooks, pick the events they care about, and the system handles fan-out, queuing, and retries.
When to reach for webhooks
Pick webhooks when an external system needs to react to forum activity in near-real time:
- Mirror new releases to a separate site, RSS feed, or Discord channel.
- Trigger a build or deploy when a new version is published.
- Push download events to an analytics warehouse or BI tool.
- Notify a moderation queue in chat when a new comment lands.
If your integration runs in PHP inside the same install, prefer a code-event listener. Webhooks add HTTP latency and queue indirection that you do not need when the consumer is local.
Content types and events
Five Downloads Manager content types fire webhooks. Standard CRUD events (insert, update, delete) fire automatically when the entity saves or deletes. Custom events fire from controller and entity hooks.
| Content type | Events |
|---|---|
mc_dm_download | insert, update, delete, download_started, download_completed, download_failed, gate_passed, gate_failed, gate_all_passed |
mc_dm_version | insert, update, delete, publish, unpublish |
mc_dm_file | insert, update, delete |
mc_dm_comment | insert, update, delete |
mc_dm_review | insert, update, delete |
Delivery model
Each event fans out to every active webhook whose event filter and criteria both match. Fan-out happens in a deferred job, so the request that triggered the event is not blocked on outbound HTTP.
One event with three matching webhooks produces three deliveries. Each delivery has its own retry counter.
Headers at a glance
Every POST carries:
XF-Content-Type: the content type (mc_dm_download,mc_dm_version, etc.).XF-Webhook-Event: the event name (update,publish,download_started, …).XF-Webhook-Id: the webhook record ID.XF-Webhook-Secret: the shared secret you configured on the endpoint, sent in plaintext.
The receiver authenticates the request by comparing XF-Webhook-Secret against its stored copy of the same secret. There is no HMAC body signature. Always serve webhook receivers over HTTPS so the secret cannot be sniffed in transit.
See Payloads for the full body shape.
Retries
A failed delivery is retried up to three times: 5 minutes, then 10 minutes, then 20 minutes after the previous attempt. After the third retry, the delivery is dropped and the failure is written to the server error log.
There is no delivery log, dead-letter view, or replay button. If you need long-term observability, log every delivery in your receiver. See Retries for the failure model in detail.
Where to next
- Subscription model: the webhook record, criteria filters, AdminCP UI walkthrough.
- Payloads: headers, body, per-event data shape.
- Retries: retry schedule, failure modes, observability.