Skip to content
Fikrr Docs

Webhooks Overview

Webhooks let you integrate with external systems in two ways:

  • Incoming webhooks — the platform receives delivery status updates and inbound messages from email and messaging providers (SendGrid, Twilio, Meta, etc.)
  • Outgoing webhooks — the platform sends HTTP POST requests to your URLs when events happen, such as a ticket being created or a survey response being submitted

Outgoing webhooks

Section titled “Outgoing webhooks”

You can configure outgoing webhooks to notify your systems when events occur. Two webhook systems are available:

  • Ticket webhooks — fire on ticket lifecycle events (created, updated, resolved, etc.) and new messages
  • Survey webhooks — fire when a survey response is completed

How delivery works

Section titled “How delivery works”
  1. When an event occurs, the platform creates a delivery record and queues an HTTP POST to each active webhook subscribed to that event.
  2. The request includes a JSON payload with event details, plus headers for event type, delivery ID, and an HMAC-SHA256 signature (if a secret is configured).
  3. If delivery fails, the platform retries with exponential backoff using the webhook’s retry policy (default: 1s, 5s, 30s, 5m, 30m, 2h).
  4. After 10 consecutive failures, the webhook is automatically disabled and an admin is notified.

Security

Section titled “Security”
  • Webhook URLs must use HTTPS.
  • URLs pointing to localhost, private IPs, or internal DNS suffixes (.internal, .local, .svc) are rejected to prevent SSRF.
  • Requests time out after 10 seconds.
  • Response bodies are captured up to 4,096 bytes for debugging.

Verifying signatures

Section titled “Verifying signatures”

If you configure a secret on your webhook, every delivery includes an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body.

To verify:

  1. Compute HMAC-SHA256 of the raw request body using your secret as the key.
  2. Hex-encode the result.
  3. Compare with the value after sha256= in the header using a constant-time comparison.

Standard headers

Section titled “Standard headers”

Every outgoing webhook request includes these headers:

HeaderDescription
Content-Typeapplication/json
X-Webhook-EventThe event type (e.g. ticket.created)
X-Webhook-DeliveryUnique delivery ID (UUID)
X-Webhook-Signaturesha256=<hmac_hex> (only if a secret is configured)

Any custom headers configured on the webhook are also included.

Incoming webhooks

Section titled “Incoming webhooks”

The platform exposes endpoints that receive callbacks from external providers. These are used internally to track delivery statuses and process inbound messages. Each provider has its own endpoint with provider-specific signature validation.

Email providers

Section titled “Email providers”

Messaging and distribution providers

Section titled “Messaging and distribution providers”
Section titled “Related pages”