Webhooks

Overview

Webhooks provide real-time notifications when events occur in the Form Platform.

Webhook Events

Available Events

• response.created - New form submission

• event.view - Form page viewed

• event.focus - Field focused

• event.submit - Form submitted

• event.error - Validation error

• event.abandon - Form abandoned

Webhook Configuration

Create Webhook

POST /webhooks
{
  "formId": "form_123",
  "event": "response.created",
  "url": "https://example.com/webhook",
  "secret": "whsec_optional_secret"
}

Webhook Settings

• URL: Endpoint to receive webhooks

• Event: Event type to subscribe to

• Secret: HMAC secret for verification

• Enabled: Enable/disable webhook

Webhook Payload

OpenTelemetry Format

{
  "resource": {
    "service.name": "form-platform",
    "service.version": "1.0.0",
    "form.id": "form_123"
  },
  "event": {
    "name": "response.created",
    "timestamp": "2024-01-01T00:00:00Z",
    "attributes": {
      "response.id": "rsp_456",
      "form.id": "form_123"
    }
  },
  "trace": {
    "trace_id": "abc123...",
    "span_id": "def456..."
  }
}

Legacy Format

For backwards compatibility, legacy fields included:

• type: Event type

• form_id: Form ID

• response_id: Response ID

• timestamp: ISO timestamp

• data: Event data

Signature Verification

HMAC Signature

Webhooks include HMAC SHA-256 signature:

Header: X-Webhook-Signature

Verification

const crypto = require('crypto');

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

Webhook Delivery

Retry Logic

• Automatic retries with exponential backoff

• Maximum 3 retry attempts

• Dead-letter queue for failures

Delivery Status

• Success: 200-299 status codes

• Failure: 4xx, 5xx status codes

• Retry: Automatic retry on failure

Best Practices

Webhook Endpoint

• Return 200 quickly

• Process asynchronously

• Idempotent processing

• Log all webhooks

Security

• Always verify signatures

• Use HTTPS endpoints

• Validate payload structure

• Rate limit webhook processing

Next Steps

• API Reference - API reference

• Security - Security best practices