Subscription model

A webhook is a single delivery target: one URL, one secret, one event filter, optionally a criteria block per content type. Webhooks are managed from AdminCP → Setup → Webhooks.

Record shape

Field	Type	Notes
webhook_id	int	Primary key.
title	varchar	Admin-facing label.
description	varchar	Optional free-text.
url	varchar	Receiver URL. HTTPS strongly recommended.
secret	varchar	Shared secret sent in the XF-Webhook-Secret header.
events	json	Map of content_type → ['*'] or content_type → [event, event, ...].
criteria	json	Map of content_type → criteria_block. See below.
content_type	enum	Payload format: json or form. Default json.
ssl_verify	bool	Enable strict TLS verification. Default on.
active	bool	Pause without deleting.

Event filter

The filter is a JSON map keyed by content type. For each content type you can opt in to specific events or all events.

{
  "mc_dm_download": ["insert", "update", "download_started"],
  "mc_dm_version": "*",
  "mc_dm_comment": ["insert"]
}

"*" for a content type means "every event of this content type, including events added in future releases." A list pins to specific events; new events added later will not fire until you edit the webhook.

If a content type is absent from the map, no event for that content type ever fires.

Criteria filters

Each Downloads Manager content type ships a criteria class so admins can narrow which records cause a delivery without writing a new webhook per category or prefix. Criteria are configured in the admin UI per content type.

Content type	Available rules
mc_dm_download	Category multi-select, prefix multi-select, password protection (any/yes/no).
mc_dm_version	Category multi-select, published state (any/yes/no).
mc_dm_file	Category multi-select, validation status (any/validated/pending/failed).
mc_dm_comment	Category multi-select.
mc_dm_review	Category multi-select, rating min/max.

Criteria evaluate against the entity's serialised payload. An empty criteria block matches everything — no filter is the default.

Admin UI walkthrough

At AdminCP → Setup → Webhooks:

1. List view. Every webhook with title, URL, content-type/event count, and active toggle.
2. Add webhook. Form fields for title, description, URL, secret, payload format, SSL verification, and a per-content-type event grid where you check the events you want to subscribe to. Each [MC] content type appears in this grid alongside the others.
3. Edit webhook. Same form. Editing the secret invalidates any receiver that hard-coded the old value; rotate carefully.
4. Toggle. Inline activate/deactivate; preserves all other settings.

There is no dead-letter view, no per-delivery log, no manual replay action, and no consecutive-failure counter. Plan accordingly when you design your receiver.

Permissions

Webhook management uses the standard admin permission for the Webhooks navigation entry. Whichever admin group can see Setup → Webhooks can manage webhooks.

Audit log

Admin changes to webhooks are written to the standard admin log. The Downloads Manager audit log (xf_mc_dm_audit_log) does not record webhook subscription edits.

Cross-link

• Payloads: what gets sent on each event.
• Retries: what happens when a receiver is unreachable.