Developer Portal | TaskNation

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in TaskNation. Instead of polling the API, you register endpoint URLs that we call with event payloads.

Setting Up Webhooks

POST /api/v2/webhooks
Authorization: Bearer {accessToken}
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/tasknation",
  "events": ["lead.created", "lead.updated", "message.received", "booking.confirmed"],
  "businessID": "468046965846925323",
  "secret": "your-webhook-signing-secret"
}

Available Events

Event	Description	Trigger
`lead.created`	New lead matched to business	Customer submits request
`lead.updated`	Lead status changed	Pro responds, customer hires, etc.
`lead.expired`	Lead expired without hire	7-day timeout
`message.received`	New message from customer	Customer sends message
`booking.confirmed`	Appointment confirmed	Customer confirms booking
`booking.cancelled`	Appointment cancelled	Either party cancels
`review.created`	New review posted	Customer leaves review
`payment.received`	Payment processed	Customer pays via platform

Webhook Payload Structure

{
  "id": "evt_abc123",
  "event": "lead.created",
  "timestamp": "2026-02-15T10:30:00Z",
  "data": {
    "leadID": "299614694480093245",
    "businessID": "468046965846925323",
    "request": {
      "category": "Interior Painting",
      "location": { "city": "San Jose", "state": "CA", "zip": "95110" }
    },
    "customer": {
      "name": "John Doe",
      "phone": "+14155550199"
    }
  }
}

Verifying Webhooks

All webhook requests include an X-TaskNation-Signature header. Verify it using HMAC-SHA256 with your webhook secret:

const crypto = require('crypto');

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

Retry Policy

If your endpoint returns a non-2xx status, we retry with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 24 hours. After 5 failed attempts, the webhook is disabled and you'll receive an email notification.