Webhooks

Instead of polling for task results, you can configure webhook endpoints in your user settings. DataTalk will send a POST request to all your active webhooks when any task completes or fails.

Setting Up Webhooks

1. Create a Webhook

Go to Settings > API > Webhooks and add a webhook endpoint. You can configure up to 10 webhooks. Each webhook gets its own signing secret, which you can copy at any time.

2. Webhook Delivery

When a task completes, DataTalk fans out a delivery to all active webhooks for the task's user. Each delivery is independent — if one webhook fails, others are unaffected.

Webhook Payload

When the task completes, DataTalk sends a POST request:

{
  "taskId": "task-456",
  "status": "COMPLETED",
  "result": { ... },
  "webhookId": "wh-789",
  "timestamp": "2025-01-15T10:05:03.000Z"
}

On failure:

{
  "taskId": "task-456",
  "status": "FAILED",
  "error": { ... },
  "webhookId": "wh-789",
  "timestamp": "2025-01-15T10:05:03.000Z"
}

Signature Verification

Webhook requests include an X-Datatalk-Signature header containing an HMAC-SHA256 hex digest of the request body, signed with the webhook's signing secret. A unique X-Datatalk-Delivery header identifies each delivery attempt.

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhookSignature(body, secret, signature) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  if (signature.length !== expected.length) return false;
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// In your webhook handler (Express example)
app.post("/webhook", express.text({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-datatalk-signature"];
  const rawBody = req.body; // raw string, not parsed JSON

  if (!signature || !verifyWebhookSignature(rawBody, WEBHOOK_SECRET, signature)) {
    return res.status(401).send("Invalid signature");
  }

  const payload = JSON.parse(rawBody);
  const { taskId, status, result, error } = payload;
  // Handle the webhook...

  res.status(200).send("OK");
});

Retry Policy

If your webhook endpoint fails to respond with a 2xx status code, DataTalk retries with exponential backoff:

After 5 failed attempts, the delivery is marked as FAILED. The task result is still available via GET /task/:taskId.

URL Requirements

• Production: Only HTTPS URLs are accepted
• Production: Private/local IPs are blocked (localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x, 172.16-31.x.x)
• Development: HTTP and local IPs are allowed
• Request timeout: 30 seconds per attempt
• Redirects are not followed (for SSRF protection)

Managing Webhooks

You can manage webhooks through the Settings UI:

• Create — Add a webhook with a name and URL (max 10)
• Toggle — Enable or disable individual webhooks
• Copy secret — Copy the signing secret at any time
• Regenerate secret — Generate a new signing secret (invalidates the old one)
• Delete — Remove a webhook and all its delivery records
• Deliveries tab — View delivery history with status, attempt count, and error details