Webhooks

Webhooks allow you to listen for events occurring in your AutomateIt workspace (e.g., incoming messages, template delivery reports, successful Paystack checkouts) and automatically trigger actions on your backend servers.

---

1. Setting Up a Webhook URL

1. Log in to your dashboard and go to Settings → Webhooks.
2. Click Add Endpoint.
3. Enter your server's destination URL (e.g., https://api.yourdomain.com/webhooks/automateit).
4. Select the events you want to listen to.
5. Click Save. The dashboard will display your Webhook Secret key, used to verify signature payloads.

---

2. Webhook Event Payloads

Event: message.received

Fired when a customer sends a new message to your connected WhatsApp number.

{
  "event": "message.received",
  "timestamp": 1782103400,
  "tenant_id": "tenant_abc123",
  "data": {
    "message_id": "wamid.HBgMMjM0ODAxMjM0NTY3OBIVAgASGBBDQ0ZEMkUzNzVFM0ZDRUI0QkUAAg==",
    "from": "2348012345678",
    "name": "Amaka Umeh",
    "type": "text",
    "text": {
      "body": "Hello, is my package ready?"
    }
  }
}

Event: message.status_updated

Fired when the status of a message you sent changes (e.g., sent, delivered, read).

{
  "event": "message.status_updated",
  "timestamp": 1782103405,
  "tenant_id": "tenant_abc123",
  "data": {
    "message_id": "msg_987654321_abc",
    "status": "read",
    "recipient": "2348012345678",
    "updated_at": "2026-06-22T10:05:00Z"
  }
}

---

3. Verifying Webhook Signatures

To ensure that the webhook requests were actually sent by AutomateIt and not by a malicious third party, you should verify the cryptographic signature included in the request headers.

Every payload request includes an X-AutomateIt-Signature header, which is a SHA-256 Hash-based Message Authentication Code (HMAC) generated using your Webhook Secret key and the raw JSON request body.

Node.js Express Example:

const crypto = require('crypto');

app.post('/webhooks/automateit', (req, res) => {
  const signature = req.headers['x-automateit-signature'];
  const rawBody = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  if (signature === expectedSignature) {
    // Request is verified, process payload event
    res.status(200).send('Verified');
  } else {
    // Invalid signature, reject request
    res.status(401).send('Unauthorized');
  }
});