Skip to content

Webhooks

Webhooks deliver real-time notifications about server events by posting to an HTTP endpoint of the operator’s choice. They let external systems react to activity in the server without polling; typical uses include recording deliveries into an analytics pipeline, flagging authentication anomalies to a SIEM, or triggering automated workflows on message ingestion.

Configuration

Section titled “Configuration”

Each webhook is represented by a WebHook object (found in the WebUI under Settings › Telemetry › Webhooks). Relevant fields are:

  • url: endpoint to which POST requests are sent.
  • events and eventsPolicy: set of events and how to interpret it. Each selected event is a key mapped to true. With eventsPolicy set to include, only the selected events trigger the webhook; with exclude, all events except the selected ones trigger it. Event identifiers are documented on the Events page.
  • timeout: maximum time to wait for a response, in milliseconds. Default 30000 (30 seconds).
  • throttle: minimum interval between batches, in milliseconds. Events that fall within the same window are grouped. Default 1000 (one second).
  • discardAfter: time in milliseconds after which an undelivered webhook request is discarded. Default 300000 (five minutes).
  • signatureKey: optional HMAC key used to sign each request body. The signature is base64-encoded and carried in the X-Signature header. The field is a SecretKeyOptional with variants None, Value, EnvironmentVariable, and File.
  • httpAuth: HTTP authentication used by the request. A nested type with variants Unauthenticated, Basic, and Bearer.
  • httpHeaders: additional HTTP headers to include on each request.
  • allowInvalidCerts: whether to permit requests to endpoints with an invalid TLS certificate. Default false.
  • lossy: whether to drop events when the endpoint is unreachable or persistently failing. When false, events accumulate until delivery succeeds or discardAfter elapses.
  • enable: whether the webhook is active.
  • level: minimum severity of events delivered to this endpoint.

API documentation

Section titled “API documentation”

Response object

Section titled “Response object”

The main object in the webhook response is WebhookEvents, which contains a list of WebhookEvent objects:

{
    "events": [
        {
            "id": "12345",
            "createdAt": "2023-06-21T14:55:00Z",
            "type": "auth.success",
            "data": {}
        }
    ]
}

Each WebhookEvent contains the following fields:

  • id (String): Unique identifier for the event.
  • createdAt (RFC3339 timestamp): Timestamp when the event was created.
  • type (WebhookType): Type of the event.
  • data (WebhookPayload): Detailed data associated with the event.

Data payload

Section titled “Data payload”

The data payload is a nested object that contains additional information about the event. The structure of the data object varies depending on the event type and it may contain any of the supported keys.

Example

Section titled “Example”

The equivalent of a webhook firing on auth.success and store.ingest, signed with a shared secret, with a custom header and Basic authentication:

{
  "url": "https://example.com/webhook",
  "events": {"auth.success": true, "store.ingest": true},
  "eventsPolicy": "include",
  "timeout": 30000,
  "throttle": 1000,
  "signatureKey": {"@type": "Value", "secret": "my-secret-key"},
  "httpHeaders": {"X-My-Header": "my-value"},
  "httpAuth": {
    "@type": "Basic",
    "username": "account",
    "secret": {"@type": "Value", "secret": "password"}
  },
  "allowInvalidCerts": false,
  "enable": true
}

Each key in events selects a single event from the EventType enum; wildcard patterns are not supported, so every event to be delivered must be listed explicitly.