Webhooks API

Webhooks allow your application to receive real-time notifications from WhatsSync. Instead of constantly polling our API for updates, webhooks push data to your server as events occur.

Setting Up Webhooks

You can configure webhooks in your WhatsSync dashboard under Webhooks Configuration. For each event type, you'll need to provide a URL where WhatsSync will send HTTP POST requests when the event occurs.

Reliable Delivery

We'll retry failed webhook deliveries multiple times to ensure your application receives all events.

Secure by Default

All webhook requests are signed with your secret key, allowing you to verify their authenticity.

Event Types

message.incoming

Triggered when a new message is received from a contact.

{
  "event": "message.incoming",
  "id": "msg_123456789",
  "timestamp": "2023-06-15T14:22:33Z",
  "data": {
    "from": "+1234567890",
    "to": "+0987654321",
    "text": "Hello, how are you?",
    "media": null,
    "timestamp": "2023-06-15T14:22:30Z"
  }
}

message.status

Triggered when a message status changes (sent, delivered, read, etc.).

{
  "event": "message.status",
  "id": "status_123456789",
  "timestamp": "2023-06-15T14:23:45Z",
  "data": {
    "messageId": "msg_987654321",
    "status": "read",
    "timestamp": "2023-06-15T14:23:40Z"
  }
}

contact.update

Triggered when contact information is updated.

{
  "event": "contact.update",
  "id": "contact_update_123456789",
  "timestamp": "2023-06-15T15:30:00Z",
  "data": {
    "contactId": "contact_123456",
    "phone": "+1234567890",
    "name": "John Doe",
    "profileImage": "https://example.com/profile.jpg"
  }
}

media.upload

Triggered when media files are uploaded.

{
  "event": "media.upload",
  "id": "media_123456789",
  "timestamp": "2023-06-15T16:45:20Z",
  "data": {
    "messageId": "msg_123456",
    "mediaType": "image",
    "mediaUrl": "https://media.whatsync.io/123456.jpg",
    "mimeType": "image/jpeg",
    "caption": "Check out this photo"
  }
}

Security

Important: Always verify webhook signatures to ensure requests are coming from WhatsSync.

All webhook requests are signed with a secret key. You should verify the signature to ensure the request is coming from WhatsSync.

Signature Verification Example

// Example signature verification in Node.js
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-whatsync-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Received valid webhook:', req.body);
  res.status(200).send('OK');
});

Best Practices

Respond Quickly

Your webhook endpoint should respond with a 200 status code as quickly as possible. Process the webhook data asynchronously if needed.

Handle Retries

WhatsSync will retry failed webhook deliveries. Make sure your endpoint is idempotent to handle the same event multiple times.

Verify Signatures

Always verify the webhook signature to ensure the request is legitimate and hasn't been tampered with.

Monitor Webhook History

Use the Webhook History page to monitor and debug webhooks. This helps identify and resolve delivery issues.

Need Help?

If you're having trouble with webhooks or have questions about implementation, our support team is here to help.

Contact Support