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, forms or achievements, or to completion types), 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.

Each ID must be an integer, or the request returns 422. IDs are not checked against existing walls, forms or achievements, and filters for an event that is not in events are ignored. Their values are still validated, so an invalid value still returns 422.

monotree.completion.created is filtered on type instead of on IDs. Pass one or more of course, journey and handbook; leave the filter out to receive all three. Any other value, including an ID, returns 422:

{
  "events": ["monotree.completion.created"],
  "filters": { "monotree.completion.created": ["course", "journey"] }
}

All other events (e.g. monotree.user.registered, monotree.onboarding.completed, monotree.announcement.published) are not entity-scoped; any filters supplied for them are ignored, though each value must still be an integer or the request returns 422.

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, with two exceptions:

• Events and filters are replaced together. Sending events replaces the endpoint's event rules with the events and filters in the same request; events without filters removes any filters. filters sent without events is ignored.
• Authentication is replaced as a set, and only when the request contains auth_type. Send auth_type, auth_value and, for api_key, auth_header together. auth_value or auth_header sent without auth_type is ignored, and auth_type sent alone clears the stored value. Send "auth_type": null to remove authentication.

Sending custom_headers replaces all custom headers; send null to remove them.

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+02:00",
    "updated_at": "2026-06-09T10:00:00+02: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 event deliveries but keeps its configuration and history, so you can switch it back on later. Toggling does not undo a revoke: on a revoked endpoint it still flips is_active, but the endpoint stays revoked and receives no events.

Revoke

POST /webhooks/{id}/revoke permanently deactivates the endpoint: it sets is_active to false and records revoked_at. An endpoint receives event deliveries only when is_active is true and revoked_at is null, and nothing undoes a revoke, neither toggle nor PUT. The record is kept and its delivery logs are kept for 90 days; there is no hard delete — this mirrors the CMS.

An endpoint also stops with the token that created it: revoking or deleting the token revokes the endpoint, and while the token is expired the endpoint receives no event deliveries. Endpoints created in the CMS, and endpoints that already existed before v0.59.0, keep running whatever the state of a token.

Test delivery

POST /webhooks/{id}/ping sends one signed delivery to the endpoint URL right away, using its current secret, auth, and custom headers. It is sent once, without retries, and works on a deactivated or revoked endpoint too. The body is the usual envelope with "event": "monotree.test" and "payload": { "message": "This is a test webhook." }.

The call answers 200 whatever the receiver did, so read ok:

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

{ "ok": false, "status": "failed", "status_code": 500, "error": "The receiver answered HTTP 500" }