Webhook Connectivity and Authentication Options

Reindeer webhook connectors receive events from external systems over HTTPS and turn each accepted payload into a record artifact that can trigger an agent workflow.

The public receive endpoint is:

POST /api/v1/webhook/workspaces/{workspace_identifier}/connectors/{connector_identifier}

The endpoint does not require Auth0. Instead, Reindeer verifies each request using the authentication method configured on the webhook connector: HMAC signature, API key header, or no verification.

When to Use Webhooks

Use a webhook connector when an external system can push events to Reindeer as they happen. Common examples include ticket updates, form submissions, order events, messaging events, document-processing callbacks, or alerts from an upstream system.

If the source system is on premises and cannot reach the public Reindeer API directly, place an outbound relay, proxy, or integration service inside the customer network and have that component deliver the webhook to Reindeer over HTTPS. For network-level patterns such as VPN, private routing, or relays, see Network Connectivity Options for On-Premises Environments.

Connectivity Patterns

Authentication Options

Webhook authentication is configured under the connector's config.auth object. Secret values are referenced through Reindeer Secret resources; they are not placed directly in the connector configuration.

HMAC Signature

Use auth_method: "hmac" when the sending system can sign requests with a shared secret. This is the preferred option for internet-facing webhook senders because Reindeer can verify both the payload and, when configured, the request timestamp.

Configuration fields:

• secret_hmac_key: Secret resource containing the HMAC signing key.
• signature_header: Header containing the signature. The default is X-Webhook-Signature. Some providers use names such as X-Hub-Signature-256.
• algorithm: sha256 by default; sha1 and sha512 are also supported.
• basestring_template: String Reindeer computes the HMAC over. The default is {body}.
• signature_encoding: hex by default; base64 is also supported.
• signature_prefix: Literal prefix to remove from the signature header before comparison, for providers that send values such as v0=....
• replay_protection: Optional timestamp validation using timestamp_header and max_skew_seconds.

The HMAC base string can include these placeholders only:

• {body}: raw request body.
• {header.<HeaderName>}: value of a request header.
• {url}: public URL the caller hit.
• {form_params_canonical}: form-encoded request body parsed, sorted by key, and joined as key/value pairs with no separators.

{
  "connector_type": "webhook",
  "auth": {
    "auth_method": "hmac",
    "secret_hmac_key": "workspaces/acme/secrets/webhook-signing-key",
    "signature_header": "X-Webhook-Signature",
    "algorithm": "sha256",
    "basestring_template": "{body}",
    "signature_encoding": "hex",
    "replay_protection": {
      "timestamp_header": "X-Webhook-Timestamp",
      "max_skew_seconds": 300
    }
  }
}

API Key Header

Use auth_method: "api_key" when the sending system can include a static secret in a request header but cannot compute HMAC signatures.

Configuration fields:

• secret_api_key: Secret resource containing the expected API key or bearer token.
• auth_header: Header Reindeer reads the token from. If omitted, Reindeer uses X-Reindeer-Webhook.

The Authorization header cannot be used for webhook API key auth because it is reserved by the API gateway. Choose a dedicated header such as X-Reindeer-Webhook, X-Webhook-Token, or a customer-specific header name.

{
  "connector_type": "webhook",
  "auth": {
    "auth_method": "api_key",
    "secret_api_key": "workspaces/acme/secrets/source-webhook-token",
    "auth_header": "X-Reindeer-Webhook"
  }
}

No Verification

Use auth_method: "none" only for trusted internal paths where access is controlled outside the webhook itself, such as a private relay, a constrained test environment, or a source protected by customer network controls.

Because the receive endpoint is public, do not use none for internet-facing sources unless another control reliably limits who can reach and call the endpoint.

{
  "connector_type": "webhook",
  "auth": {
    "auth_method": "none"
  }
}

Payload Validation and Case Resume

A webhook connector can include an optional payload_schema to validate incoming JSON before the event is accepted. Invalid JSON or payloads that fail schema validation return 400.

To resume an existing Reindeer case instead of starting a new run, the sender may include X-Reindeer-Case-Id. When that header is present, Reindeer uses the connector's user_input_path to extract the user input from the webhook payload and append it to the resumed case. The case ID header is not part of the HMAC signed base string.

What the Sending Team Provides

• Source system name, event types, expected request volume, and retry behavior.
• Webhook payload examples and a JSON Schema if payload validation should be enforced.
• Preferred authentication method: HMAC, API key header, or no verification for a controlled internal path.
• For HMAC: signing key, signature header, algorithm, signature encoding, base string construction, optional prefix, and timestamp/replay requirements.
• For API key: token value, header name, and rotation process.
• For on-premises or restricted sources: egress path, relay/proxy owner, DNS and firewall requirements, and any customer network approval process.

Operational Behavior

• 202: webhook accepted; response includes the created record artifact resource name.
• 400: invalid JSON body or payload validation failure.
• 401: missing or invalid signature/API key.
• 404: connector not found.
• 413: request body exceeds the maximum size.

Related Articles

• Reindeer API Reference
• Network Connectivity Options for On-Premises Environments
• Data Privacy, Isolation, and LLM Provider Controls