Skip to content
CognizyCognizyHelp
Sign in
In this area

Webhooks

Manage webhook endpoints, deliveries and replays.

List webhooks

get/v1/public/webhooks

Parameters

No parameters.

Responses

  • 200Webhooks list returned

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/webhooks" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Create webhook

post/v1/public/webhooks

Accepts Idempotency-Key

Registers a webhook endpoint. The HMAC signing secret is returned ONCE in the response — store it; we never expose it again.

Parameters

No parameters.

Body (JSON)required

urlstring (uri)required
Target URL that will receive the POST. Must be HTTPS in production.
eventsstring[]required
List of event names to subscribe to.
descriptionstringoptional
Optional human-readable description for this webhook.
whatsAppInstanceIdsstring[]optional
Only deliver events from these WhatsApp numbers (ids from GET /whatsapp/instances). Empty or omitted = every number. Events without a number (contacts, deals, website chat) are always delivered.

Responses

  • 201Webhook created. The signing secret is returned ONCE here.
  • 400Missing url or invalid event list

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/webhooks" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://api.example.com/webhooks/cognizy",
  "events": [
    "message.created",
    "conversation.closed"
  ],
  "description": "Sync incoming messages with Salesforce",
  "whatsAppInstanceIds": [
    "whatsAppInstance_123"
  ]
}'

Get webhook by id

get/v1/public/webhooks/{id}

Parameters

idstringrequired· path
Webhook ID

Responses

  • 200Webhook returned
  • 404Webhook not found

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/webhooks/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Update webhook

patch/v1/public/webhooks/{id}

Accepts Idempotency-Key

Parameters

idstringrequired· path
Webhook ID

Body (JSON)required

urlstring (uri)optional
eventsstring[]optional
descriptionstringoptional
isActivebooleanoptional
Set false to pause delivery without deleting the webhook. Re-enabling resets the failure streak.
whatsAppInstanceIdsstring[]optional
Only deliver events from these WhatsApp numbers (ids from GET /whatsapp/instances). Empty or omitted = every number. Events without a number (contacts, deals, website chat) are always delivered.

Responses

  • 200Webhook updated
  • 400Invalid event list
  • 404Webhook not found

Examples

bash
curl -X PATCH "https://api.cognizy.ai/api/v1/public/webhooks/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://example.com/webhooks/cognizy",
  "events": [
    "texto"
  ],
  "description": "texto",
  "isActive": true,
  "whatsAppInstanceIds": [
    "whatsAppInstance_123"
  ]
}'

Delete webhook

delete/v1/public/webhooks/{id}

Parameters

idstringrequired· path
Webhook ID

Responses

  • 204Webhook deleted
  • 404Webhook not found

Examples

bash
curl -X DELETE "https://api.cognizy.ai/api/v1/public/webhooks/<id>" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Send a test event

post/v1/public/webhooks/{id}/test

Accepts Idempotency-Key

Dispatches a webhook.test event to the configured URL using the current signing secret.

Parameters

idstringrequired· path
Webhook ID

Responses

  • 200Test event dispatched
  • 404Webhook not found

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/webhooks/<id>/test" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Rotate webhook secret

post/v1/public/webhooks/{id}/rotate-secret

Accepts Idempotency-Key

Issues a new signing secret. The previous one stays valid for 24h, with both signatures emitted in X-Cognizy-Signature (v1=<new>,v1=<old>).

Parameters

idstringrequired· path
Webhook ID

Responses

  • 200New signing secret returned (shown ONCE)
  • 404Webhook not found

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/webhooks/<id>/rotate-secret" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

List webhook deliveries

get/v1/public/webhooks/{id}/deliveries

Parameters

idstringrequired· path
Webhook ID
limitstringoptional· query

Responses

  • 200Deliveries list returned
  • 404Webhook not found

Examples

bash
curl -X GET "https://api.cognizy.ai/api/v1/public/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $COGNIZY_API_KEY"

Replay a webhook delivery

post/v1/public/webhooks/deliveries/{deliveryId}/replay

Accepts Idempotency-Key

Re-sends the payload of a previous delivery to the webhook URL.

Parameters

deliveryIdstringrequired· path
Webhook delivery ID

Responses

  • 200Delivery replayed
  • 404Delivery not found

Examples

bash
curl -X POST "https://api.cognizy.ai/api/v1/public/webhooks/deliveries/<deliveryId>/replay" \
  -H "Authorization: Bearer $COGNIZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Full reference