Skip to content
HuddleX 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”

HuddleX receives delivery-status and inbound-message callbacks from the email and messaging providers it’s connected to. For most providers (Twilio, SendGrid, Meta, and the rest) this is wired up automatically when you connect the channel — there’s nothing to configure and no payload format you control.

Two incoming endpoints are different: their payload is defined by HuddleX and you point your email provider at them.

  • Inbound email — forward customer email replies here to turn them into ticket messages
  • Email delivery status — send delivery, bounce, open, and failure notifications here
Section titled “Related pages”