API reference

Webhooks

Subscribe endpoints to receive HMAC-signed events, validate a URL before subscribing, pause or delete a subscription and rotate the secret at any time.

7 operations
Base URLhttps://api.messages.ccxcompany.co
AuthenticationBearer with your API key

The technical text below comes from the public contract, openapi.json, in the language the contract was written in.

List webhook subscriptions

GET/webhooks

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

Parameters

Field	In	Type	Description
`status`optional	query	`string`	Values:`activepausedfailingrevoked`
`event`optional	query	`string`	Values:`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`
`limit`optional	query	`integer`
`skip`optional	query	`integer`

Responses

200Default Response

Response fields and example

Field	Type	Description
`items`required	`object[]`
`items[].id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`items[].organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`items[].url`required	`string · uri`
`items[].secretCipher`required	`string`	PII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
`items[].secretVersion`required	`integer`
`items[].headers`optional	`object[]`
`items[].headers[].key`required	`string`
`items[].headers[].value`required	`string`
`items[].events`required	`string[]`
`items[].status`required	`string`	Values:`activepausedfailingrevoked`
`items[].description`optional	`string`
`items[].retry`required	`object`
`items[].retry.maxAttempts`required	`integer`
`items[].retry.backoffSeconds`required	`integer`
`items[].createdById`optional	`string`	Branded Account id (`acc_` prefix + 21 nano-id chars).
`items[].consecutiveFailures`optional	`integer`
`items[].lastSuccessAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].lastFailureAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`items[].updatedAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`total`required	`integer`

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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/webhooks' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

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>

Request body`application/json`

Field	Type	Description
`url`required	`string · uri`	HTTPS endpoint that will receive signed POST requests.
`events`required	`string[]`	Subscribed events. Closed enum from `WEBHOOK_EVENTS`.
`description`optional	`string`
`headers`optional	`object[]`	Custom headers forwarded on every delivery + the ping. Values are encrypted at rest; reserved (`X-CCX-*`, `Host`, …) names are rejected.
`headers[].key`required	`string`
`headers[].value`required	`string`
`retry`optional	`object`
`retry.maxAttempts`required	`integer`
`retry.backoffSeconds`required	`integer`

Full body example

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

Responses

201Default Response

Response fields and example

Field	Type	Description
`webhook`required	`object`
`webhook.id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`webhook.organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`webhook.url`required	`string · uri`
`webhook.secretCipher`required	`string`	PII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
`webhook.secretVersion`required	`integer`
`webhook.headers`optional	`object[]`
`webhook.headers[].key`required	`string`
`webhook.headers[].value`required	`string`
`webhook.events`required	`string[]`
`webhook.status`required	`string`	Values:`activepausedfailingrevoked`
`webhook.description`optional	`string`
`webhook.retry`required	`object`
`webhook.retry.maxAttempts`required	`integer`
`webhook.retry.backoffSeconds`required	`integer`
`webhook.createdById`optional	`string`	Branded Account id (`acc_` prefix + 21 nano-id chars).
`webhook.consecutiveFailures`optional	`integer`
`webhook.lastSuccessAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`webhook.lastFailureAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`webhook.createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`webhook.updatedAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`reveal`required	`object`
`reveal.id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`reveal.secret`required	`string`	Plaintext signing secret. Returned once by POST /webhooks and POST /webhooks/:id/rotate-secret. Caller MUST store it — it cannot be retrieved later.
`reveal.secretVersion`required	`integer`
`reveal.createdAt`required	`string · date-time`	ISO-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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

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

Required fields only. Swap the sample values for your own.

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.

Request body`application/json`

Field	Type	Description
`url`required	`string`	Endpoint to validate. Checked for HTTPS + SSRF + a live signed `webhook.ping`.
`headers`optional	`object[]`	Custom headers to include on the ping (as they would be on delivery).
`headers[].key`required	`string`
`headers[].value`required	`string`

Full body example

JSON

{  "url": "https://api.partner.test/ccx/webhook",  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ]}

Responses

200Result of the pre-create ping. ok:true ⇒ endpoint returned 2xx; ok:false carries a reason the modal renders inline.
Response fields and example
Field Type Description
okrequired boolean
statusCodeoptional integer
latencyMsoptional integer
reasonoptional string Values:invalid_urlinsecure_schemessrf_blockednon_2xxtimeoutunreachable
messageoptional string
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).

Field	Type	Description
`ok`required	`boolean`
`statusCode`optional	`integer`
`latencyMs`optional	`integer`
`reason`optional	`string`	Values:`invalid_urlinsecure_schemessrf_blockednon_2xxtimeoutunreachable`
`message`optional	`string`

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

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

Required fields only. Swap the sample values for your own.

Get a single webhook subscription

GET/webhooks/{id}

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

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`url`required	`string · uri`
`secretCipher`required	`string`	PII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
`secretVersion`required	`integer`
`headers`optional	`object[]`
`headers[].key`required	`string`
`headers[].value`required	`string`
`events`required	`string[]`
`status`required	`string`	Values:`activepausedfailingrevoked`
`description`optional	`string`
`retry`required	`object`
`retry.maxAttempts`required	`integer`
`retry.backoffSeconds`required	`integer`
`createdById`optional	`string`	Branded Account id (`acc_` prefix + 21 nano-id chars).
`consecutiveFailures`optional	`integer`
`lastSuccessAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`lastFailureAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`required	`string · date-time`	ISO-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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

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.

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).

Request body`application/json`

Field	Type	Description
`events`optional	`string[]`
`status`optional	`string`	Values:`activepaused`
`description`optional	`string`
`headers`optional	`object[]`	Replaces the full custom-header set. `[]` clears all.
`headers[].key`required	`string`
`headers[].value`required	`string`
`retry`optional	`object`
`retry.maxAttempts`required	`integer`
`retry.backoffSeconds`required	`integer`

Full body example

JSON

{  "events": [    "message.sent"  ],  "status": "active",  "description": "string",  "headers": [    {      "key": "X-Api-Key",      "value": "sk_live_…"    }  ],  "retry": {    "maxAttempts": 8,    "backoffSeconds": 60  }}

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`organizationId`required	`string`	Branded Organization id (`org_` prefix + 21 nano-id chars).
`url`required	`string · uri`
`secretCipher`required	`string`	PII_CRITICAL — encrypted webhook signing secret (JSON-serialized EncryptedBlob, AAD bound to org+webhook). Never returned in plaintext after creation.
`secretVersion`required	`integer`
`headers`optional	`object[]`
`headers[].key`required	`string`
`headers[].value`required	`string`
`events`required	`string[]`
`status`required	`string`	Values:`activepausedfailingrevoked`
`description`optional	`string`
`retry`required	`object`
`retry.maxAttempts`required	`integer`
`retry.backoffSeconds`required	`integer`
`createdById`optional	`string`	Branded Account id (`acc_` prefix + 21 nano-id chars).
`consecutiveFailures`optional	`integer`
`lastSuccessAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`lastFailureAt`optional	`string · date-time`	ISO-8601 timestamp in UTC.
`createdAt`required	`string · date-time`	ISO-8601 timestamp in UTC.
`updatedAt`required	`string · date-time`	ISO-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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X PATCH 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Content-Type: application/json" \  -d '{}'

Required fields only. Swap the sample values for your own.

Delete a webhook subscription

DELETE/webhooks/{id}

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

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).

Responses

204Webhook removed.
401RFC 7807 problem details for UNAUTHORIZED (401).
403RFC 7807 problem details for FORBIDDEN (403).
404RFC 7807 problem details for NOT_FOUND (404).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X DELETE 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

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).

Parameters

Field	In	Type	Description
`id`required	path	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).

Responses

200Default Response

Response fields and example

Field	Type	Description
`id`required	`string`	Branded Webhook id (`wbh_` prefix + 21 nano-id chars).
`secret`required	`string`	Plaintext signing secret. Returned once by POST /webhooks and POST /webhooks/:id/rotate-secret. Caller MUST store it — it cannot be retrieved later.
`secretVersion`required	`integer`
`createdAt`required	`string · date-time`	ISO-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).

Error responses follow RFC 7807 (application/problem+json), with a stable code in the code field. See the error codes

curl example

cURL

curl -X POST 'https://api.messages.ccxcompany.co/webhooks/wbh_uV2aLwzXMqNmKjHbPiRoT/rotate-secret' \  -H "Authorization: Bearer $CCX_API_KEY"

Required fields only. Swap the sample values for your own.

Stuck on a route? Talk to the people who run the API.

Start free Talk to sales

Webhooks

List webhook subscriptions

Parameters

Responses

curl example

Subscribe a webhook endpoint

Request body`application/json`

Responses

curl example

Validate an endpoint before subscribing

Request body`application/json`

Responses

curl example

Get a single webhook subscription

Parameters

Responses

curl example

Patch webhook config

Parameters

Request body`application/json`

Responses

curl example

Delete a webhook subscription

Parameters

Responses

curl example

Rotate the HMAC signing secret

Parameters

Responses

curl example

Other API areas

Stuck on a route? Talk to the people who run the API.

Webhooks

List webhook subscriptions

Parameters

Responses

curl example

Subscribe a webhook endpoint

Request bodyapplication/json

Responses

curl example

Validate an endpoint before subscribing

Request bodyapplication/json

Responses

curl example

Get a single webhook subscription

Parameters

Responses

curl example

Patch webhook config

Parameters

Request bodyapplication/json

Responses

curl example

Delete a webhook subscription

Parameters

Responses

curl example

Rotate the HMAC signing secret

Parameters

Responses

curl example

Other API areas

Stuck on a route? Talk to the people who run the API.

Request body`application/json`

Request body`application/json`

Request body`application/json`