Webhooks

List the organization's webhook subscriptions

platform.webhooks.list

Lists every webhook subscription of the organization with its status, events, last delivery and 7-day success rate, plus the plan's cap of active subscriptions. Secrets and the values of static headers never come back. Owners and admins only. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:read scope.

Scope

developer_platform:read

Permission

View the module · Only owner, admin

MCP tool

platform_webhooks_listOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.list".

Declared cost: up to 101 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/webhooks" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/webhooks" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one webhook subscription

platform.webhooks.get

Returns one webhook subscription with its events, status, counters and last delivery. The signing secret is never returned: rotate it to get a new one. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:read scope.

Scope

developer_platform:read

Permission

View the module · Only owner, admin

MCP tool

platform_webhooks_getOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.get".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

List the event types a webhook can subscribe to

platform.webhooks.events

Returns the catalog of event types a webhook can subscribe to, one row per event in a flat list: type, module, group, a one-line summary and a description of when it fires. Filter with module, or ask for one event with type to get its example payload too (include_examples brings the example of every listed event: the whole catalog with examples does not fit in one response). Through the MCP, without module, type or include_examples, the rows come without description (a light index of every event: ask with module or type to read when each one fires); through the API every row has it. Use it to pick events before creating a subscription. Owners and admins only; the events of a private module only where it is enabled, and those of a module MB Suite has not opened for the organization, or that only carry the data of a platform whose terms do not allow sending it this way, are not listed; an event that carries it only sometimes (a lead from that platform, a change on it) is listed, does not arrive when it carries it, and arrives without that platform's fields when they are only part of it (the permissions guide lists the platforms). 400 invalid_input (param type) when type is not an event type. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:read scope.

Scope

developer_platform:read

Permission

View the module · Only owner, admin

MCP tool

platform_webhooks_eventsOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.events".

Declared cost: up to 1 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/webhooks/events" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/webhooks/events" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a webhook subscription

platform.webhooks.create

Creates a subscription that receives the chosen events at an https URL, signed with a secret that is returned ONCE in this response (store it: it cannot be read again, only rotated). The destination must be a public host: private, internal and MB Suite's own addresses are rejected. A workspace can also listen to its child accounts with child_scope. Only the event types platform.webhooks.events lists for the organization are accepted (400 invalid_input otherwise). Up to 20 active subscriptions per organization. Owners and admins only. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope.

Scope

developer_platform:write

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_createOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.create".

Declared cost: up to 2 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/webhooks" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "events": [
    "crm.lead.created"
  ]
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/webhooks" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "URL",
  "events": [
    "crm.lead.created"
  ]
}'

Edit, disable or reactivate a webhook subscription

platform.webhooks.update

Changes the URL (re-checked against private addresses; the failure streak restarts), description, events, child scope, payload mode, static headers or status of a subscription. New events must be ones platform.webhooks.events lists for the organization (400 invalid_input otherwise). status=disabled_user pauses it (queued deliveries are cancelled); status=active reactivates it and, with resend_failed=true, re-queues what failed or was cancelled in the 72 hours before it was disabled (once per delivery; it needs the API and the MCP turned on for the organization: 403 otherwise, and nothing changes). Owners and admins only. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope.

Scope

developer_platform:write

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_updateOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.update".

Declared cost: up to 4503 reads and 8601 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a webhook subscription

platform.webhooks.delete

Deletes the subscription, its signing secret and cancels its queued deliveries. Past deliveries stay 30 days for the record. This is not a customer record, so it does not go to the trash and cannot be undone: outside the screen it requires a dry run and a confirm_token. Owners and admins only. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope and permission to delete.

Needs confirmation: first dry_run: true (preview and confirm_token, valid 10 minutes and for one run), then the same body with confirm_token. In a few operations only with certain data: the description says when. Why and how: Dry run and confirm_token.

Scope

developer_platform:write and “Allow deletions” (developer_platform:delete in OAuth)

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_deleteOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.delete".

Declared cost: up to 4001 reads and 8001 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/webhooks/{webhook_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "dry_run": true
}'

Send a test event to one subscription

platform.webhooks.test

Sends a webhook.test event to this subscription only, signed and delivered exactly like a real one (with retries), even if the subscription is disabled: it is the way to check the receiver and the signature before relying on real events or reactivating. It needs the API and the MCP turned on for the organization: otherwise 403 with the reason (platform_not_enabled, platform_requires_paid_plan…) and nothing is sent. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope.

Scope

developer_platform:write

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_testOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.test".

Events it can emit

webhook.test

Declared cost: up to 2 reads and 3 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/test" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/test" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Rotate the signing secret of a subscription

platform.webhooks.rotate_secret

Generates a new signing secret and returns it ONCE. For 24 hours every delivery is signed with both the new and the previous secret (two v1= values in MB-Signature), so the receiver can switch without missing events. Owners and admins only. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope.

Scope

developer_platform:write

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_rotate_secretOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.rotate_secret".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/rotate-secret" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/rotate-secret" \
  -H "Authorization: Bearer $MB_TEST_KEY"

List the deliveries of a subscription

platform.webhooks.deliveries.list

Lists the deliveries of one subscription, newest first, with status, attempt count, response code and the attempts' details (up to 12 per delivery). Filter by one status or several to see what failed or is still retrying. Deliveries are kept 30 days. Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:read scope.

Scope

developer_platform:read

Permission

View the module · Only owner, admin

MCP tool

platform_webhooks_deliveries_listOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.deliveries.list".

Declared cost: up to 103 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one delivery with the request that was sent

platform.webhooks.deliveries.get

Returns a delivery with its attempts, the event it carried and the request as it was sent (headers and body, in the payload mode and API version fixed when the event was emitted). The signature value is not reproduced and static header values are masked. The data of connected platforms whose terms do not allow it through the API does not come: an event that carries it answers 403 platform_terms_restricted, and the rest comes without those fields (the permissions guide lists the platforms). Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:read scope.

Scope

developer_platform:read

Permission

View the module · Only owner, admin

MCP tool

platform_webhooks_deliveries_getOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.deliveries.get".

Declared cost: up to 3 reads and 0 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries/{delivery_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries/{delivery_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Resend a delivery to its destination

platform.webhooks.deliveries.resend

Queues a new delivery of the same event to the same subscription, right now, with the full retry schedule. The original delivery is kept and marked as resent; the new one points to it with resend_of. The subscription must be active, and the API and the MCP turned on for the organization (403 with the reason otherwise, and nothing is queued). Module: API & MCP (developer_platform), even though the id starts with platform.; the credential needs the developer_platform:write scope.

Scope

developer_platform:write

Permission

Edit in the module · Only owner, admin

MCP tool

platform_webhooks_deliveries_resendOn the full surface; on the compact one, mb_execute_operation with id: "platform.webhooks.deliveries.resend".

Declared cost: up to 2 reads and 3 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resend" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resend" \
  -H "Authorization: Bearer $MB_TEST_KEY"