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.

Escopo

developer_platform:read

Permissão

Ver o módulo · Só owner, admin

Tool do MCP

platform_webhooks_listNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.list".

Custo declarado: até 101 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Sem parâmetros.

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:read

Permissão

Ver o módulo · Só owner, admin

Tool do MCP

platform_webhooks_getNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.get".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:read

Permissão

Ver o módulo · Só owner, admin

Tool do MCP

platform_webhooks_eventsNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.events".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:write

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_createNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.create".

Custo declarado: até 2 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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"
  ]
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:write

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_updateNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.update".

Custo declarado: até 4503 leituras e 8601 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

developer_platform:write e «Permitir exclusões» (developer_platform:delete no OAuth)

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_deleteNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.delete".

Custo declarado: até 4001 leituras e 8001 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:write

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_testNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.test".

Eventos que pode emitir

webhook.test

Custo declarado: até 2 leituras e 3 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:write

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_rotate_secretNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.rotate_secret".

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:read

Permissão

Ver o módulo · Só owner, admin

Tool do MCP

platform_webhooks_deliveries_listNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.deliveries.list".

Custo declarado: até 103 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:read

Permissão

Ver o módulo · Só owner, admin

Tool do MCP

platform_webhooks_deliveries_getNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.deliveries.get".

Custo declarado: até 3 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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.

Escopo

developer_platform:write

Permissão

Editar no módulo · Só owner, admin

Tool do MCP

platform_webhooks_deliveries_resendNa superfície completa; na compacta, mb_execute_operation com id: "platform.webhooks.deliveries.resend".

Custo declarado: até 2 leituras e 3 escritas por chamada (contam na cota diária).

Parâmetros

Resposta

Erros

Exemplo

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

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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