Webhooks

Webhooks notify your backend about actionable or asynchronous changes. They are an acceleration path, not the system of record: always reconcile the related resource through the API.

Create an endpoint

curl https://api.fideralabs.com/v1/webhook_endpoints \
  --request POST \
  --header "Authorization: Bearer $FIDERA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/fidera",
    "events": [
      "check.completed",
      "monitor.matches_changed",
      "flow_session.started",
      "submission.completed"
    ]
  }'

The whsec_ signing secret is returned once. Store it immediately in your secret manager. Fidera cannot show the plaintext secret later.

Supported event names are:

• check.completed
• check.failed
• batch.completed
• monitor.check_completed
• monitor.matches_changed
• monitor.failed
• flow_session.started
• flow_session.resumed
• flow_session.expired
• submission.completed

Flow-session events identify the Flow and device session without including the capability secret, session token, applicant evidence, or Check results. submission.completed means the applicant journey is closed to further writes; retrieve the tenant-authenticated Flow and its Checks separately when your backend is authorized to process them.

The previous onboarding.session_* and onboarding.completed names remain available as subscription values during migration, but new integrations should use the resource-based names above.

Verify signatures

Each request includes:

• Fidera-Webhook-Id
• Fidera-Webhook-Timestamp
• Fidera-Webhook-Signature

Compute HMAC-SHA256 with the endpoint secret over:

{timestamp}.{event_id}.{raw_request_body}

Use the exact raw bytes received, compare signatures in constant time, reject timestamps outside your replay window, and persist the event ID before applying side effects.

Delivery behavior

Respond with a successful 2xx only after you durably accept the event. Keep the handler fast by enqueueing downstream work. Delivery is at least once, so duplicate event IDs are expected and must be harmless.

Filter delivery history at GET /v1/webhook_deliveries. Manually retry a failed attempt with POST /v1/webhook_deliveries/{delivery_id}/retry.

Endpoint operations

You can list, inspect, update, enable or disable, and delete endpoints. Secret rotation returns the new secret once and invalidates the old signing value; coordinate deployment so receivers accept the new secret before relying on delivery.