StatusDesenvolvedoresParceirosPTENESEntrar
Falar com vendasCriar conta grátis
Criar conta grátis
Falar com vendasCriar conta grátis
EntrarStatusPTENES

Referência da API

Webhooks

Assine endpoints para receber eventos assinados com HMAC, valide a URL antes de assinar, pause ou apague uma assinatura e troque o segredo quando quiser.

  • 7 operações
  • URL basehttps://api.messages.ccxcompany.co
  • AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

List webhook subscriptions

GET/webhooks

Returns paginated list. Filters: status, event, limit, skip. The secretCipher field is the encrypted blob — never the plaintext secret.

Parâmetros

CampoOndeTipoDescrição
statusopcionalquerystringValores:activepausedfailingrevoked
eventopcionalquerystringValores:message.sentmessage.deliveredmessage.readmessage.failedmessage.receivedcampaign.completednumber.quality_changedtemplate.approvedtemplate.rejectedcontact.createdcontact.opted_outapikey.createdapikey.rotatedsms.deliveredsms.failedsms.undeliveredsms.receivedemail.deliveredemail.bouncedemail.complainedemail.openedemail.clickedrcs.deliveredrcs.readrcs.failedsms.clickedrcs.clickedwallet.low_balancewallet.depletedinstagram.message.receivedinstagram.message.sentinstagram.message.failed
limitopcionalqueryinteger
skipopcionalqueryinteger

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    itemsobrigatórioobject[]
    items[].idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    items[].organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    items[].urlobrigatóriostring · uri
    items[].secretCipherobrigatóriostringPII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
    items[].secretVersionobrigatóriointeger
    items[].headersopcionalobject[]
    items[].headers[].keyobrigatóriostring
    items[].headers[].valueobrigatóriostring
    items[].eventsobrigatóriostring[]
    items[].statusobrigatóriostringValores:activepausedfailingrevoked
    items[].descriptionopcionalstring
    items[].retryobrigatórioobject
    items[].retry.maxAttemptsobrigatóriointeger
    items[].retry.backoffSecondsobrigatóriointeger
    items[].createdByIdopcionalstringBranded Account id (acc_ prefix + 21 nano-id chars).
    items[].consecutiveFailuresopcionalinteger
    items[].lastSuccessAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    items[].lastFailureAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    items[].createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    items[].updatedAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    totalobrigatóriointeger
    JSON
    {  "items": [    {      "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",      "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",      "url": "https://api.partner.test/ccx/webhook",      "secretCipher": "string",      "secretVersion": 1,      "headers": [        {          "key": "X-Api-Key",          "value": "sk_live_…"        }      ],      "events": [        "message.sent"      ],      "status": "active",      "description": "string",      "retry": {        "maxAttempts": 8,        "backoffSeconds": 60      },      "createdById": "acc_dEws32WQG1MgvOVa6wqXT",      "consecutiveFailures": 0,      "lastSuccessAt": "2026-04-07T17:30:00.000Z",      "lastFailureAt": "2026-04-07T17:30:00.000Z",      "createdAt": "2026-04-07T17:30:00.000Z",      "updatedAt": "2026-04-07T17:30:00.000Z"    }  ],  "total": 3}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/webhooks' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Subscribe a webhook endpoint

POST/webhooks

Creates a webhook subscription with a fresh HMAC signing secret. The secret is encrypted at rest by the PII guardian (AES-256-GCM, AAD bound to org+webhook id) and returned exactly once in the reveal.secret field of the response. Caller MUST store it — it cannot be retrieved later.

Signing convention (Step 19 worker will use this):

  • Algorithm: HMAC-SHA256(secret, "${unix_ts}.${rawBody}")
  • Header: X-CCX-Signature: t=<unix>,v1=<hex>
  • Headers: X-CCX-Webhook-Id, X-CCX-Event, X-CCX-Delivery-Id
  • Secret format: whsec_<base64url>

Corpo da requisiçãoapplication/json

CampoTipoDescrição
urlobrigatóriostring · uriHTTPS endpoint that will receive signed POST requests.
eventsobrigatóriostring[]Subscribed events. Closed enum from WEBHOOK_EVENTS.
descriptionopcionalstring
headersopcionalobject[]Custom headers forwarded on every delivery + the ping. Values are encrypted at rest; reserved (X-CCX-*, Host, …) names are rejected.
headers[].keyobrigatóriostring
headers[].valueobrigatóriostring
retryopcionalobject
retry.maxAttemptsobrigatóriointeger
retry.backoffSecondsobrigatóriointeger
Exemplo completo do corpo
JSON
{  "url": "https://api.partner.test/ccx/webhook",  "events": [    "message.delivered",    "message.failed"  ],  "description": "Production CRM sync",  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ],  "retry": {    "maxAttempts": 8,    "backoffSeconds": 60  }}

Respostas

  • 201Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    webhookobrigatórioobject
    webhook.idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    webhook.organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    webhook.urlobrigatóriostring · uri
    webhook.secretCipherobrigatóriostringPII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
    webhook.secretVersionobrigatóriointeger
    webhook.headersopcionalobject[]
    webhook.headers[].keyobrigatóriostring
    webhook.headers[].valueobrigatóriostring
    webhook.eventsobrigatóriostring[]
    webhook.statusobrigatóriostringValores:activepausedfailingrevoked
    webhook.descriptionopcionalstring
    webhook.retryobrigatórioobject
    webhook.retry.maxAttemptsobrigatóriointeger
    webhook.retry.backoffSecondsobrigatóriointeger
    webhook.createdByIdopcionalstringBranded Account id (acc_ prefix + 21 nano-id chars).
    webhook.consecutiveFailuresopcionalinteger
    webhook.lastSuccessAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    webhook.lastFailureAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    webhook.createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    webhook.updatedAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    revealobrigatórioobject
    reveal.idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    reveal.secretobrigatóriostringPlaintext signing secret. Returned once by POST /webhooks and POST /webhooks/:id/rotate-secret. Caller MUST store it — it cannot be retrieved later.
    reveal.secretVersionobrigatóriointeger
    reveal.createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    JSON
    {  "webhook": {    "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",    "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",    "url": "https://api.partner.test/ccx/webhook",    "secretCipher": "string",    "secretVersion": 1,    "headers": [      {        "key": "X-Api-Key",        "value": "sk_live_…"      }    ],    "events": [      "message.sent"    ],    "status": "active",    "description": "string",    "retry": {      "maxAttempts": 8,      "backoffSeconds": 60    },    "createdById": "acc_dEws32WQG1MgvOVa6wqXT",    "consecutiveFailures": 0,    "lastSuccessAt": "2026-04-07T17:30:00.000Z",    "lastFailureAt": "2026-04-07T17:30:00.000Z",    "createdAt": "2026-04-07T17:30:00.000Z",    "updatedAt": "2026-04-07T17:30:00.000Z"  },  "reveal": {    "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",    "secret": "whsec_aB3xY9zQ1pTkLmNoPqRsTuVwXyZ123456",    "secretVersion": 1,    "createdAt": "2026-04-07T17:30:00.000Z"  }}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/webhooks' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://api.partner.test/ccx/webhook",    "events": [      "message.delivered",      "message.failed"    ]  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Validate an endpoint before subscribing

POST/webhooks/validate

Pre-create check for the dashboard's Validar button. Runs the same SSRF guardian the dispatcher uses, then fires a single signed webhook.ping POST (ephemeral secret) and reports reachability.

Always 200; the body's ok flag carries the verdict and reason/message describe a failure (invalid URL, non-HTTPS, SSRF-blocked, non-2xx, timeout, unreachable) so the modal can render it inline.

Corpo da requisiçãoapplication/json

CampoTipoDescrição
urlobrigatóriostringEndpoint to validate. Checked for HTTPS + SSRF + a live signed webhook.ping.
headersopcionalobject[]Custom headers to include on the ping (as they would be on delivery).
headers[].keyobrigatóriostring
headers[].valueobrigatóriostring
Exemplo completo do corpo
JSON
{  "url": "https://api.partner.test/ccx/webhook",  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ]}

Respostas

  • 200Result of the pre-create ping. ok:true ⇒ endpoint returned 2xx; ok:false carries a reason the modal renders inline.

    Campos e exemplo da resposta
    CampoTipoDescrição
    okobrigatórioboolean
    statusCodeopcionalinteger
    latencyMsopcionalinteger
    reasonopcionalstringValores:invalid_urlinsecure_schemessrf_blockednon_2xxtimeoutunreachable
    messageopcionalstring
    JSON
    {  "ok": true,  "statusCode": 200,  "latencyMs": 142,  "reason": "invalid_url",  "message": "string"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/webhooks/validate' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://api.partner.test/ccx/webhook"  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Get a single webhook subscription

GET/webhooks/{id}

Returns the full record. Cross-tenant requests get 404 (Mongo Guardian filter).

Parâmetros

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    urlobrigatóriostring · uri
    secretCipherobrigatóriostringPII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
    secretVersionobrigatóriointeger
    headersopcionalobject[]
    headers[].keyobrigatóriostring
    headers[].valueobrigatóriostring
    eventsobrigatóriostring[]
    statusobrigatóriostringValores:activepausedfailingrevoked
    descriptionopcionalstring
    retryobrigatórioobject
    retry.maxAttemptsobrigatóriointeger
    retry.backoffSecondsobrigatóriointeger
    createdByIdopcionalstringBranded Account id (acc_ prefix + 21 nano-id chars).
    consecutiveFailuresopcionalinteger
    lastSuccessAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    lastFailureAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    updatedAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    JSON
    {  "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "url": "https://api.partner.test/ccx/webhook",  "secretCipher": "string",  "secretVersion": 1,  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ],  "events": [    "message.sent"  ],  "status": "active",  "description": "string",  "retry": {    "maxAttempts": 8,    "backoffSeconds": 60  },  "createdById": "acc_dEws32WQG1MgvOVa6wqXT",  "consecutiveFailures": 0,  "lastSuccessAt": "2026-04-07T17:30:00.000Z",  "lastFailureAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Patch webhook config

PATCH/webhooks/{id}

Partial update. URL is IMMUTABLE — to change the endpoint, delete + recreate (which forces a new secret). status accepts active / paused only; failing / revoked are managed by the Step 19 worker.

Parâmetros

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).

Corpo da requisiçãoapplication/json

CampoTipoDescrição
eventsopcionalstring[]
statusopcionalstringValores:activepaused
descriptionopcionalstring
headersopcionalobject[]Replaces the full custom-header set. [] clears all.
headers[].keyobrigatóriostring
headers[].valueobrigatóriostring
retryopcionalobject
retry.maxAttemptsobrigatóriointeger
retry.backoffSecondsobrigatóriointeger
Exemplo completo do corpo
JSON
{  "events": [    "message.sent"  ],  "status": "active",  "description": "string",  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ],  "retry": {    "maxAttempts": 8,    "backoffSeconds": 60  }}

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    organizationIdobrigatóriostringBranded Organization id (org_ prefix + 21 nano-id chars).
    urlobrigatóriostring · uri
    secretCipherobrigatóriostringPII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
    secretVersionobrigatóriointeger
    headersopcionalobject[]
    headers[].keyobrigatóriostring
    headers[].valueobrigatóriostring
    eventsobrigatóriostring[]
    statusobrigatóriostringValores:activepausedfailingrevoked
    descriptionopcionalstring
    retryobrigatórioobject
    retry.maxAttemptsobrigatóriointeger
    retry.backoffSecondsobrigatóriointeger
    createdByIdopcionalstringBranded Account id (acc_ prefix + 21 nano-id chars).
    consecutiveFailuresopcionalinteger
    lastSuccessAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    lastFailureAtopcionalstring · date-timeISO-8601 timestamp in UTC.
    createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    updatedAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    JSON
    {  "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",  "organizationId": "org_pGgniw5L7CTDSZDwjDrQ2",  "url": "https://api.partner.test/ccx/webhook",  "secretCipher": "string",  "secretVersion": 1,  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ],  "events": [    "message.sent"  ],  "status": "active",  "description": "string",  "retry": {    "maxAttempts": 8,    "backoffSeconds": 60  },  "createdById": "acc_dEws32WQG1MgvOVa6wqXT",  "consecutiveFailures": 0,  "lastSuccessAt": "2026-04-07T17:30:00.000Z",  "lastFailureAt": "2026-04-07T17:30:00.000Z",  "createdAt": "2026-04-07T17:30:00.000Z",  "updatedAt": "2026-04-07T17:30:00.000Z"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X PATCH 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Delete a webhook subscription

DELETE/webhooks/{id}

Hard delete. The encrypted secret is removed with the row.

Parâmetros

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).

Respostas

  • 204Webhook removed.

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X DELETE 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Rotate the HMAC signing secret

POST/webhooks/{id}/rotate-secret

Generates a new whsec_… secret, encrypts it with a fresh IV/tag (same AAD binding), bumps secretVersion, and returns the plaintext once. The previous secret is invalid immediately — there is no grace window in Step 13 (Step 19 may add an overlap window for zero-downtime rotation).

Parâmetros

CampoOndeTipoDescrição
idobrigatóriocaminhostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostringBranded Webhook id (wbh_ prefix + 21 nano-id chars).
    secretobrigatóriostringPlaintext signing secret. Returned once by POST /webhooks and POST /webhooks/:id/rotate-secret. Caller MUST store it — it cannot be retrieved later.
    secretVersionobrigatóriointeger
    createdAtobrigatóriostring · date-timeISO-8601 timestamp in UTC.
    JSON
    {  "id": "wbh_uV2aLwzXMqNmKjHbPiRoT",  "secret": "whsec_aB3xY9zQ1pTkLmNoPqRsTuVwXyZ123456",  "secretVersion": 1,  "createdAt": "2026-04-07T17:30:00.000Z"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT/rotate-secret' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátisFalar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.