Webhooks API

Configure webhooks to receive real-time notifications when form events occur. Webhooks use OpenTelemetry-style payloads and include signed headers for verification.

Create Webhook

POST /webhooks

Creates a new webhook configuration. Webhooks will be triggered for the specified events.

Request Body

{
  "formId": "form_123", // Optional - omit for all forms
  "url": "https://example.com/webhook",
  "secret": "your-webhook-secret",
  "events": [
    "response.created",
    "response.updated",
    "event.view",
    "event.focus",
    "event.abandon"
  ],
  "active": true
}

Webhook Events

response.created

Triggered when a form submission is successfully created.

response.updated

Triggered when a response is updated (status change, notes added, etc.).

event.view

Triggered when a user views a form.

event.focus

Triggered when a user focuses on a form field.

event.abandon

Triggered when a user abandons a form without submitting.

Webhook Payload

Webhooks use OpenTelemetry-style payloads with resource attributes and event details:

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

Webhook Security

All webhook requests include signed headers for verification. Verify the signature using the webhook secret:

Header: x-formr-signature
Header: x-formr-timestamp
Always verify the timestamp to prevent replay attacks
Use HMAC-SHA256 to verify the signature

List Webhooks

GET /webhooks

Lists all webhooks for the current environment. Can be filtered by form ID.

Update Webhook

PUT /webhooks/{id}

Updates an existing webhook configuration.

Delete Webhook

DELETE /webhooks/{id}

Deletes a webhook configuration. No more events will be sent to this URL.

Retry Logic

Formr automatically retries failed webhook deliveries with exponential backoff. Failed webhooks are sent to a dead-letter queue after maximum retries.

Forms API →Submissions API →