API & Developers

Webhook Events and Configuration

1 min readMar 19, 2026

HelpKit Webhooks

Webhooks let HelpKit push real-time event data to your server. Instead of polling the API, your application receives instant notifications when things happen.

Setting Up a Webhook

1.Go to Settings → API → Webhooks → Add Webhook

2.Enter your Endpoint URL (must be publicly accessible HTTPS)

3.Choose the Events to subscribe to

4.Copy the Webhook Secret (used for payload verification)

5.Click Save

Available Webhook Events

| Event | When It Fires | |-------|---------------| | message.received | New inbound message | | message.sent | Outbound message sent | | message.delivered | Message delivered to device | | message.read | Message read by recipient | | message.failed | Delivery failed | | conversation.created | New conversation opened | | conversation.assigned | Conversation assigned to agent | | conversation.resolved | Conversation marked resolved | | contact.created | New contact added | | contact.updated | Contact data changed | | campaign.sent | Campaign send initiated | | campaign.completed | All messages dispatched |

Webhook Payload Structure

json

{
  "event": "message.received",
  "timestamp": "2026-03-19T09:00:00Z",
  "data": {
    "id": "msg_xyz789",
    "conversation_id": "conv_123",
    "from": "+919876543210",
    "text": "Hi, I need help with my order",
    "type": "text"
  }
}

Verifying Webhook Signatures

HelpKit signs every webhook with HMAC-SHA256 using your webhook secret:

javascript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return expected === signature;
}

The signature is in the X-HelpKit-Signature header.

Retry Behavior

•HelpKit retries failed webhooks up to 5 times with exponential backoff

•Webhooks that fail all retries are logged in Settings → Webhooks → Failed Deliveries

•Respond with HTTP 200 within 5 seconds to acknowledge receipt