Webhooks

Overview

Webhooks allow your systems to receive automatic notifications when key events occur during an assessment. Instead of polling the API, register a webhook endpoint and we'll send you a POST request when something happens.

Setting Up Webhooks

POST /v1/webhooks

Request Body

{
  "url": "https://your-app.com/webhooks/friender",
  "events": [
    "assessment.phase_changed",
    "assessment.completed",
    "integration.connected",
    "integration.disconnected"
  ],
  "secret": "whsec_your_signing_secret"
}

Event Types

Webhook Payload

All webhook payloads follow the same envelope format:

{
  "id": "evt_abc123",
  "type": "assessment.phase_changed",
  "timestamp": "2025-01-20T14:30:00Z",
  "data": {
    "assessmentId": "asmt_abc123",
    "previousPhase": "connect",
    "currentPhase": "mapping",
    "progress": 25
  }
}

Verifying Signatures

Every webhook request includes a X-Friender-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret. Always verify this signature before processing the webhook.

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 code or times out (30 second limit), we'll retry the webhook with exponential backoff:

• 1st retry: 1 minute after initial attempt
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 12 hours (final attempt)

After 5 failed attempts, the webhook is marked as failed and you'll receive an email notification. You can manually replay failed webhooks from the dashboard.

See also: Assessment API or Authentication.