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": ["alert.created", "alert.changed", "batch.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:

• alert.created
• alert.changed
• disposition.created
• batch.completed
• monitor.failed

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.