Creating Your First Webhook

1. Prepare your receiver

Use a publicly accessible HTTPS endpoint and your application API key. Implement the combined receiver before registration: it authenticates the custom header, echoes the empty-body validation token without demanding HMAC, and durably stores signed events before acknowledging them.

2. Register and verify

curl -X POST 'https://app.chatt2.me/v1/organization/webhook' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Customer events",
    "endpoint": "https://your-server.example/webhooks/chatt2me",
    "authenticationProtocol": "NoAuthentication",
    "headers": [{"key": "X-Webhook-Secret", "value": "YOUR_RECEIVER_SECRET"}],
    "requiresSignature": true
  }'

label, endpoint and authenticationProtocol are required. headers and requiresSignature are optional. There is no eventType field on webhook creation or updates. The receiver must accept the configured authentication during verification as well as events.

Save the returned id and signing secret securely; configure the signing secret on your receiver before live deliveries. Successful validation returns active: true, isVerified: true and verifiedAt. Failed validation leaves the webhook inactive/unverified; inspect its validation log, fix the receiver, and revalidate. Do not infer success merely from webhook creation.

3. Subscribe a channel

Both IDs must belong to the exact application selected by the key. This route also supports a Sandbox application channel.

curl -X POST 'https://app.chatt2.me/v1/communication/channel/CHANNEL_UUID/webhook/WEBHOOK_UUID/configure' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"events": ["message", "message_echoes", "sent", "delivered", "read", "failed"], "enabled": true}'

This is a WhatsApp example; use the provider-specific names. Read the binding back:

curl 'https://app.chatt2.me/v1/communication/channel/CHANNEL_UUID/webhook/WEBHOOK_UUID/config' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

{
  "applicationChannelId": "6cbd6789-1d2b-47e0-9391-5eb91d2839ea",
  "webhookId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
  "events": ["message", "message_echoes", "sent", "delivered", "read", "failed"],
  "enabled": true
}

The configuration replaces the subscription list for this binding. enabled: false pauses it; events: [] removes it. Normal events require an active webhook, an enabled binding and a matching subscription. For WhatsApp Coexistence history import, subscribe one active binding to both message and message_echoes before starting import in the dashboard.

4. Update the existing webhook

Use PATCH on the saved ID, rather than creating a second webhook to add authentication:

curl -X PATCH 'https://app.chatt2.me/v1/organization/webhook/WEBHOOK_UUID' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"headers": [{"key": "X-Webhook-Secret", "value": "NEW_RECEIVER_SECRET"}], "active": true}'

headers is replace-all: omission preserves configured headers, [] clears them, and a supplied array replaces them. Include every header you still need. Changing the endpoint or authentication protocol, supplying headers, or sending active: true triggers verification. Resending only the same URL does not. Failed verification deactivates the webhook.

requiresSignature: true generates a new secret on every PATCH containing that value, even if signing was already enabled. Omit it to preserve the secret. false disables signing. Store any returned new secret securely and coordinate receiver rotation with in-flight deliveries.

Receiver authentication protocols

These protocols authenticate Hub to your receiver; they do not replace x-api-key when your integration calls Hub. Accepted values are case-sensitive:

Protocol	Configuration
NoAuthentication	No generated auth header; use a custom secret header
BasicAuthentication	X-Basic-Username and X-Basic-Password generate Authorization: Basic …
JWT	X-JWT-Token generates Authorization: Bearer …; Hub does not issue your receiver's JWT
Oauth20	Configure X-OAuth-Token-Url, X-OAuth-Client-Id, X-OAuth-Client-Secret; optional X-OAuth-Grant-Type defaults to client_credentials and X-OAuth-Token-Type defaults to Bearer
Chatt2MeForSalesforce	Use the Salesforce integration configured for your account; provide salesforceDomain when creating or changing its target

For example, the following is a complete replacement of authentication headers on an existing webhook:

{
  "authenticationProtocol": "BasicAuthentication",
  "headers": [
    {"key": "X-Basic-Username", "value": "YOUR_RECEIVER_USERNAME"},
    {"key": "X-Basic-Password", "value": "YOUR_RECEIVER_PASSWORD"}
  ]
}

{
  "authenticationProtocol": "JWT",
  "headers": [{"key": "X-JWT-Token", "value": "YOUR_RECEIVER_ISSUED_JWT"}]
}

{
  "authenticationProtocol": "Oauth20",
  "headers": [
    {"key": "X-OAuth-Token-Url", "value": "https://auth.your-server.example/token"},
    {"key": "X-OAuth-Client-Id", "value": "YOUR_CLIENT_ID"},
    {"key": "X-OAuth-Client-Secret", "value": "YOUR_CLIENT_SECRET"}
  ]
}

Use the protocol configuration fields above rather than relying on a manually supplied Authorization header: creation/update processes those special headers before deriving authorization. Salesforce configuration rejects manually supplied Authorization and X-OAuth-* headers. X-Basic-*, X-JWT-* and X-OAuth-* are configuration headers, not forwarded receiver headers. Protect credentials and keep them out of browser code and logs. Missing configuration can prevent authentication/verification; choosing a protocol alone does not provision credentials. Use the receiver's authorization checks for both validation and events. Signing remains a separate raw-body integrity check.

List, delete and rotate

curl 'https://app.chatt2.me/v1/organization/webhook' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

curl -X DELETE 'https://app.chatt2.me/v1/organization/webhook/WEBHOOK_UUID' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

Successful deletion returns 204 with no body.

curl -X POST 'https://app.chatt2.me/v1/organization/webhook/WEBHOOK_UUID/redefine-signature' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

This returns the new signing secret. In-flight requests signed with the prior secret require a coordinated transition at your receiver. See signature verification, logs, and retry.