Webhooks

Manage the endpoints cmdsend delivers email events to.

For the payload format, signature verification and retry behaviour, see the Webhooks guide.

POST/v1/webhooks

Create an endpoint

Returns the signing secret — the only time it is ever returned. An account may hold up to 10 endpoints.

Body

Parameter	Description
`url` stringrequired	Public https URL to POST events to. Private and internal addresses are rejected.
`description` string	Free-text label, up to 200 characters.
`event_types` string[]	Events to subscribe to. Defaults to all of them.

Request

cURL

curl -X POST https://api.cmdsend.com/v1/webhooks \
  -H "Authorization: Bearer cmd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/cmdsend",
    "description": "Production API",
    "event_types": ["email.delivered", "email.bounced"]
  }'

Response 201

{
  "id": "wh_a1b2c3d4-...",
  "url": "https://yourapp.com/webhooks/cmdsend",
  "description": "Production API",
  "event_types": [
    "email.delivered",
    "email.bounced"
  ],
  "is_active": true,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_success_at": "2026-09-10T12:00:03.000Z",
  "last_failure_at": null,
  "created_at": "2026-09-01T09:00:00.000Z",
  "updated_at": "2026-09-10T12:00:03.000Z",
  "secret": "whsec_..."
}

GET/v1/webhooks

List endpoints

Also returns event_types, the full list of events available to subscribe to. Secrets are never included.

Response 200

{
  "data": [
    {
      "id": "wh_a1b2c3d4-...",
      "url": "https://yourapp.com/webhooks/cmdsend",
      "description": "Production API",
      "event_types": [
        "email.delivered",
        "email.bounced"
      ],
      "is_active": true,
      "disabled_reason": null,
      "consecutive_failures": 0,
      "last_success_at": "2026-09-10T12:00:03.000Z",
      "last_failure_at": null,
      "created_at": "2026-09-01T09:00:00.000Z",
      "updated_at": "2026-09-10T12:00:03.000Z"
    }
  ],
  "event_types": [
    "email.sent",
    "email.delivered",
    "…"
  ]
}

GET/v1/webhooks/:id

Retrieve an endpoint

Response 200

{
  "id": "wh_a1b2c3d4-...",
  "url": "https://yourapp.com/webhooks/cmdsend",
  "description": "Production API",
  "event_types": [
    "email.delivered",
    "email.bounced"
  ],
  "is_active": true,
  "disabled_reason": null,
  "consecutive_failures": 0,
  "last_success_at": "2026-09-10T12:00:03.000Z",
  "last_failure_at": null,
  "created_at": "2026-09-01T09:00:00.000Z",
  "updated_at": "2026-09-10T12:00:03.000Z"
}

PATCH/v1/webhooks/:id

Update an endpoint

Change the URL, the subscriptions, or pause delivery. Setting is_active: true also clears an automatic disable and resets the failure counter.

Body

Parameter	Description
`url` string	Public https URL to POST events to. Private and internal addresses are rejected.
`description` string	Free-text label, up to 200 characters.
`event_types` string[]	Events to subscribe to. Defaults to all of them.
`is_active` boolean	Pause or resume delivery to this endpoint.

Request

cURL

curl -X PATCH https://api.cmdsend.com/v1/webhooks/$ENDPOINT_ID \
  -H "Authorization: Bearer cmd_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

DELETE/v1/webhooks/:id

Delete an endpoint

Deletes the endpoint and its delivery history. Events stop immediately. Responds 204 with no body.

POST/v1/webhooks/:id/rotate-secret

Rotate the signing secret

Issues a new secret and returns it once. It takes effect immediately with no overlap window — update your receiver before calling this.

Response 200

{
  "id": "wh_a1b2c3d4-...",
  "secret": "whsec_..."
}

POST/v1/webhooks/:id/test

Send a test event

Queues a sample email.delivered event, signed exactly like a real one. The endpoint must be active.

Response 202

{
  "delivery_id": "a1b2c3d4-...",
  "status": "pending"
}

GET/v1/webhooks/:id/deliveries

List deliveries

Recent delivery attempts for one endpoint, newest first.

Query parameters

Parameter	Description
`limit` number	Default 25, max 100.
`status` string	Filter by pending, delivered, or failed.

Response 200

{
  "data": [
    {
      "id": "d1e2f3a4-...",
      "email_id": "a1b2c3d4-...",
      "event_type": "email.delivered",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "error": null,
      "created_at": "2026-09-10T12:00:03.000Z",
      "last_attempt_at": "2026-09-10T12:00:03.400Z",
      "delivered_at": "2026-09-10T12:00:03.400Z"
    }
  ]
}