Menú

Referencia de la API · API y MCP

Webhooks

developer_platform · webhooks · 11 operaciones

GET/v1/webhooksList the organization's webhook subscriptions GET/v1/webhooks/{webhook_id}Get one webhook subscription GET/v1/webhooks/eventsList the event types a webhook can subscribe to POST/v1/webhooksCreate a webhook subscription PATCH/v1/webhooks/{webhook_id}Edit, disable or reactivate a webhook subscription DELETE/v1/webhooks/{webhook_id}Delete a webhook subscription POST/v1/webhooks/{webhook_id}/testSend a test event to one subscription POST/v1/webhooks/{webhook_id}/rotate-secretRotate the signing secret of a subscription GET/v1/webhooks/{webhook_id}/deliveriesList the deliveries of a subscription GET/v1/webhooks/{webhook_id}/deliveries/{delivery_id}Get one delivery with the request that was sent POST/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resendResend a delivery to its destination

GET/v1/webhooks

List the organization's webhook subscriptions

platform.webhooks.list

LecturaIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:read
Permiso: Ver el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_listEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.list".

Costo declarado: hasta 101 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

Sin parámetros.

Respuesta

dataarray<object>

max_activenumber

Errores

role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

GET/v1/webhooks/{webhook_id}

Get one webhook subscription

platform.webhooks.get

LecturaIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:read
Permiso: Ver el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_getEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.get".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

Respuesta

webhookobject

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

GET/v1/webhooks/events

List the event types a webhook can subscribe to

platform.webhooks.events

LecturaIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:read
Permiso: Ver el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_eventsEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.events".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

modulestringqueryopcional

Only the events of this module (crm, task_management…: the module of each event).

typestringqueryopcional

Only this event type (crm.deal.created…), with its example payload.

include_examplesbooleanqueryopcional

Bring the example payload of every listed event (by default only with type: the full catalog with examples is too large for one response).

Por defecto: false

Respuesta

dataarray<object>

Errores

role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

POST/v1/webhooks

Create a webhook subscription

platform.webhooks.create

EscrituraDesde 2026-11-01

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.

Instrucciones para agentes

Show the secret to the person once and tell them to store it now. Explain that MB-Signature is an HMAC-SHA256 of ${t}.${body} and that retries continue for 72 hours.

Alcance: developer_platform:write
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_createEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.create".

Costo declarado: hasta 2 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

urlstringcuerporequerido

The https address that receives the deliveries (a POST per event, signed with the subscription's secret). Private and internal addresses are refused.

eventsarray<enum>cuerporequerido

The event types to receive, as platform.webhooks.events lists them (crm.deal.created…).

Valores: crm.lead.created, crm.deal.created, crm.deal.stage_changed, crm.deal.won, crm.deal.lost, crm.deal.reopened, crm.deal.archived, crm.deal.updated, crm.deal.deleted, crm.person.created, crm.person.updated, crm.person.deleted, crm.company.created, crm.company.updated, crm.company.deleted, crm.activity.created, job.completed, monitors.monitor.assigned, monitors.monitor.unassigned, monitors.template.published, dashboards.dashboard.created, dashboards.dashboard.deleted, dashboards.dashboard.exported, dashboards.template.published, reports.instance.generated, reports.instance.finalized, reports.instance.published, reports.pdf.ready, reports.pdf.failed, reports.template.published

descriptionstringcuerpoopcional

A note to recognize the subscription (up to 200 characters).

child_scope"all" | array<string>cuerpoopcional

Only for a workspace: also receive the events of its Accounts, all of them (all) or a list of account ids (platform.orgs.list). Empty: only the workspace's own events.

Por defecto: []

payload_modeenumcuerpoopcional

snapshot: each delivery carries the record as it was at the event; thin: only its ids (read the record with the API).

Valores: snapshot, thin · Por defecto: "snapshot"

api_versionenumcuerpoopcional

The API version that shapes the payload (the current one by default).

Valores: 2026-11-01 · Por defecto: "2026-11-01"

headers_staticobjectcuerpoopcional

Fixed headers sent with every delivery (an authorization token of your receiver, for example): up to 5, names with letters, digits and dashes; the headers MB Suite sets (mb-signature, content-type…) cannot be overridden.

Respuesta

webhookobject

secretstring

Errores

role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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"
  ]
}'

PATCH/v1/webhooks/{webhook_id}

Edit, disable or reactivate a webhook subscription

platform.webhooks.update

EscrituraIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:write
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.update".

Costo declarado: hasta 4503 lecturas y 8601 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

updatesobjectcuerporequerido

What changes: only the fields sent.

Respuesta

webhookobject

resentnumber

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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/v1/webhooks/{webhook_id}

Delete a webhook subscription

platform.webhooks.delete

IrreversibleDesde 2026-11-01

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.

Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.

Alcance: developer_platform:write y «Permitir eliminar» (developer_platform:delete en OAuth)
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.delete".

Costo declarado: hasta 4001 lecturas y 8001 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

Respuesta

webhook_idstring

Errores

webhook_not_found delete_not_allowed confirmation_required role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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
}'

POST/v1/webhooks/{webhook_id}/test

Send a test event to one subscription

platform.webhooks.test

EscrituraDesde 2026-11-01

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.

Alcance: developer_platform:write
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_testEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.test".
Eventos que puede emitir: webhook.test

Costo declarado: hasta 2 lecturas y 3 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

messagestringcuerpoopcional

A text for the test event (Hello from MB Suite by default).

Respuesta

event_idstring | null

deliveriesnumber

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

POST/v1/webhooks/{webhook_id}/rotate-secret

Rotate the signing secret of a subscription

platform.webhooks.rotate_secret

EscrituraDesde 2026-11-01

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.

Alcance: developer_platform:write
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_rotate_secretEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.rotate_secret".

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

Respuesta

secretstring

secret_prefixstring

previous_secret_expires_atnumber

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

GET/v1/webhooks/{webhook_id}/deliveries

List the deliveries of a subscription

platform.webhooks.deliveries.list

LecturaIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:read
Permiso: Ver el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_deliveries_listEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.deliveries.list".

Costo declarado: hasta 103 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

statusenumqueryopcional

Only the deliveries in this status: pending, retrying, succeeded, failed, disabled (the subscription was off, or the API and the MCP stayed off for the organization for 72 hours: platform_off) or skipped_scope (outside its child scope).

Valores: pending, retrying, succeeded, failed, disabled, skipped_scope

statusesarray<enum>queryopcional

Several statuses at once (pending and retrying: the ones still on their way).

Valores: pending, retrying, succeeded, failed, disabled, skipped_scope

limitintegerqueryopcional

How many deliveries this page brings at most.

Por defecto: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came; without it, the first page.

Respuesta

dataarray<object>

has_moreboolean

next_cursorstring

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

GET/v1/webhooks/{webhook_id}/deliveries/{delivery_id}

Get one delivery with the request that was sent

platform.webhooks.deliveries.get

LecturaIdempotenteDesde 2026-11-01

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.

Alcance: developer_platform:read
Permiso: Ver el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_deliveries_getEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.deliveries.get".

Costo declarado: hasta 3 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

delivery_idstringrutarequerido

The delivery id (platform.webhooks.deliveries.list).

Respuesta

deliveryobject

eventobject | null

The event it carried; null when it is no longer kept.

requestobject | null

The request as it was sent; null without its event, or when it was not sent because a platform's terms do not allow it.

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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

POST/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/resend

Resend a delivery to its destination

platform.webhooks.deliveries.resend

EscrituraDesde 2026-11-01

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.

Alcance: developer_platform:write
Permiso: Editar en el módulo · Solo owner, admin
Tool del MCP: platform_webhooks_deliveries_resendEn la superficie completa; en la compacta, mb_execute_operation con id: "platform.webhooks.deliveries.resend".

Costo declarado: hasta 2 lecturas y 3 escrituras por llamada (cuentan en el cupo diario).

Parámetros

webhook_idstringrutarequerido

The webhook subscription id (platform.webhooks.list).

delivery_idstringrutarequerido

The delivery id (platform.webhooks.deliveries.list).

Respuesta

delivery_idstring

Errores

webhook_not_found role_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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