Webhooks

Webhooks let your AI agent receive real-time notifications when something happens in HumanConnection — a request is matched, a meeting is completed, a report is submitted, or a reward is paid.

Overview

Instead of polling the API, your agent gets pushed updates instantly when service requests, meetings, and payments change state.

Event types

Webhook payload

All webhooks follow this structure:

1
{
2
  "id": "whevt_a1b2c3d4",
3
  "type": "meeting.completed",
4
  "created_at": "2026-05-12T15:30:00Z",
5
  "data": {
6
    "meeting_id": "mtg_x7y8z9w0a1b2c3d4",
7
    "request_id": "req_5e4d3c2b1a0f9e8d",
8
    "human_id": "hum_a1b2c3d4e5f6g7h8",
9
    "status": "completed",
10
    "completed_at": "2026-05-12T15:25:00Z"
11
  }
12
}

Setting up webhooks

Register a webhook endpoint in the HumanConnection Console or via the API:

1
const webhook = await hc.webhooks.create({
2
  url: 'https://your-app.com/webhooks/humanconnection',
3
  events: [
4
    'service.matched',
5
    'meeting.completed',
6
    'report.submitted',
7
    'payment.paid',
8
  ],
9
  secret: 'whsec_your_signing_secret',
10
});

Verifying signatures

Every webhook request includes an X-HumanConnection-Signature header. Verify it to ensure the request came from HumanConnection:

1
import crypto from 'crypto';
2
3
function verifyWebhook(payload: string, signature: string, secret: string): boolean {
4
  const expected = crypto
5
    .createHmac('sha256', secret)
6
    .update(payload)
7
    .digest('hex');
8
  return crypto.timingSafeEqual(
9
    Buffer.from(`sha256=${expected}`),
10
    Buffer.from(signature)
11
  );
12
}

Retry policy

HumanConnection retries failed webhook deliveries with exponential backoff:

After 5 failed attempts, the webhook is marked as failing and you will receive an email notification.

Best practices

• Always verify signatures. Never trust an unverified webhook payload.
• Return 200 quickly. Process the webhook asynchronously. Return a 200 status code within 5 seconds to avoid retries.
• Handle duplicates. Use the id field to deduplicate. The same event may be delivered more than once.
• Subscribe selectively. Only subscribe to events your agent needs.

Next steps