Copy page

Developers

Webhooks

Configure webhooks to receive real-time notifications when events occur in your Qwetty organization.

How webhooks work

When an event happens (e.g., a new message arrives), Qwetty sends an HTTP POST request to your configured webhook URL with the event data.

Setting up a webhook

1. Go to Settings → Channel and find the Webhook Settings section
2. Click Create Webhook
3. Configure:
   • Name — A descriptive name
   • URL — Your HTTPS endpoint
   • Events — Which events to receive (messages, status updates, contacts, media)
   • Secret — A shared secret for HMAC signature verification
4. Save and activate

Event types

Qwetty currently emits message events:

Event	Description
message.incoming	A message was received from a contact
message.outgoing	A message was sent from your organization

The webhook settings expose message, status, contact, and media toggles, but only the message events are emitted today. The toggle key for both events above is message.

Webhook payload

Each delivery is a JSON body with exactly three fields:

Code
{
  "event": "message.incoming",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": { }
}

The delivery also sets an X-Qwetty-Event header with the event name. There is no top-level organizationId in the payload.

Verifying signatures

When your webhook has a secret, Qwetty signs each delivery with HMAC-SHA256 over the raw request body (the exact { event, timestamp, data } JSON string) and sends the hex digest in the X-Qwetty-Signature header. Verify against the raw body — not a re-serialized object:

Code
const crypto = require('crypto');

// `rawBody` is the exact request body string Qwetty sent
function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Testing locally

Use a tool like ngrok to expose your local server:

Code
ngrok http 3000

Then use the ngrok URL as your webhook endpoint during development.

Best practices

• Always verify signatures to ensure requests come from Qwetty
• Respond quickly — Qwetty waits up to 10 seconds for a response before timing out
• Don't rely on retries — Delivery is fire-and-forget; failures are logged but not retried, so make your endpoint resilient
• Use HTTPS — Webhook URLs must use HTTPS in production

Next steps

• Conversation & Webhook Settings — Where webhooks are configured
• API Reference — Full endpoint documentation