Webhooks

What are Webhooks?

Webhooks are automated HTTP POST requests that dat2ai sends to your server whenever specific events occur on your site. Instead of polling the API for new events, your server receives them in real time.

For example, you can receive an instant notification in Slack when an AI agent submits a contact form, or log the interaction in your CRM system automatically.

Setup

Create a webhook endpoint from the dat2ai dashboard to start receiving event notifications.

Payload Format

Each webhook delivery sends a JSON payload containing an array of events and metadata:

{
  "events": [
    {
      "event_id": "evt_abc123",
      "site_id": "site_xyz",
      "tool_name": "contact-form",
      "event_type": "invocation",
      "agent_type": "browser_agent",
      "consent_given": true,
      "timestamp": "2026-02-16T12:00:00Z"
    }
  ],
  "siteId": "site_xyz",
  "timestamp": "2026-02-16T12:00:00Z"
}

The events array can contain one or more events. Events are batched for efficiency — your endpoint may receive multiple events in a single request.

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request came from dat2ai and was not tampered with.

Here is a Node.js example for verifying the webhook signature:

const crypto = require('crypto');

function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');

  const valid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );

  return valid;
}

// Express.js example
app.post('/webhook', (req, res) => {
  if (!verifyWebhookSignature(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { events } = req.body;
  for (const event of events) {
    console.log('Received:', event.event_type, event.tool_name);
  }

  res.status(200).json({ received: true });
});

Always use crypto.timingSafeEqual for signature comparison to prevent timing attacks. Never use simple string equality (===).

Event Types

The following event types can trigger webhook deliveries:

Delivery

How dat2ai delivers webhook notifications to your endpoint:

Use Cases