Manage Outgoing Webhooks

Manage outgoing webhook endpoints over the API instead of the Open API → Outgoing Webhooks tab in the CMS. This is the same set of capabilities — create an endpoint, choose the events it subscribes to (optionally filtered to specific walls or forms), configure authentication and custom headers, send a test delivery, and revoke or deactivate it — so external systems can set up integrations without a human in the CMS.

For the catalog of events and their delivery payloads, see Outgoing Webhooks.

Required scope: read:webhooks, write:webhooks.

Endpoints

Create

curl -X POST https://customer.monotree.com/api/open/v1/webhooks \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My integration",
    "url": "https://example.com/monotree/webhook",
    "events": ["monotree.post.created", "monotree.user.registered"],
    "filters": { "monotree.post.created": [1, 3] },
    "auth_type": "bearer_token",
    "auth_value": "your-receiving-endpoint-token",
    "custom_headers": { "X-Tenant": "acme" }
  }'

Request body

A new endpoint is active immediately and is issued a signing secret. The response masks the secret — fetch the full value once with GET /webhooks/{id}/secret.

Filtering events

Some events are tied to an entity and can be narrowed to specific instances by passing their IDs under filters, keyed by event name. An event with no filter (or a non-filterable event) fires for all matching activity.

All other events (e.g. monotree.user.registered, monotree.onboarding.completed, monotree.formresponse.alarm_triggered) are not entity-scoped; any filters supplied for them are ignored.

Authenticating deliveries

Beyond the HMAC signature (see Outgoing Webhooks), you can have Monotree add an auth header to every delivery:

Update

PUT accepts the same fields as create; only what you send is changed. Sending events (with optional filters) replaces the endpoint's existing event rules.

curl -X PUT https://customer.monotree.com/api/open/v1/webhooks/42 \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "events": ["monotree.announcement.published"] }'

Response

{
  "data": {
    "id": 42,
    "name": "My integration",
    "url": "https://example.com/monotree/webhook",
    "is_active": true,
    "events": ["monotree.post.created", "monotree.user.registered"],
    "filters": { "monotree.post.created": [1, 3] },
    "auth_type": "bearer_token",
    "custom_headers": { "X-Tenant": "••••" },
    "secret": "a1b2c3d4...",
    "total_deliveries": 0,
    "last_used_at": null,
    "revoked_at": null,
    "created_at": "2026-06-09T10:00:00+00:00",
    "updated_at": "2026-06-09T10:00:00+00:00"
  }
}

Revealing the secret

Returns the full HMAC signing secret so you can verify delivery signatures.

curl https://customer.monotree.com/api/open/v1/webhooks/42/secret \
  -H "Authorization: Bearer mono_your_token_here"

{ "data": { "secret": "a1b2c3d4e5f6..." } }

Activate / deactivate

POST /webhooks/{id}/toggle flips is_active. A deactivated endpoint stops receiving deliveries but keeps its configuration and history, so you can switch it back on later.

Revoke

POST /webhooks/{id}/revoke permanently deactivates the endpoint and records revoked_at. The record and its delivery logs are kept for audit; there is no hard delete — this mirrors the CMS.

Test delivery

POST /webhooks/{id}/ping sends a signed monotree.test payload to the endpoint URL using its current secret, auth, and custom headers. The response reports whether the delivery succeeded:

{ "ok": true, "status": "delivered" }