Webhooks

The Gateway can notify your system when events occur. When a subscribed event happens, the Gateway sends an HTTP request to your endpoint with a structured JSON payload.

See Events for the full list of event types and their payload schemas.

Requirements:

• HTTPS with a valid, publicly trusted certificate (TLS 1.2+).
• Must accept one of: POST (recommended), PUT, or PATCH.
• Must respond with a 2xx status within 10 seconds to be considered delivered.

Headers

We send the following headers with each webhook request:

• Content-Type: application/json.
• User-Agent: Venus Gateway/1.0.0 (+https://venus.bayern).
• Hook-Id: Unique identifier for the webhook (e.g., 60c72b2f9b1e8c001c8e4d3b).
• Event: The event type that triggered the webhook (e.g., entity.created).
• Date: The UTC timestamp of when the event occurred (e.g., 2023-10-01T12:00:00Z).
• Content-Digest: See MDN for details on Content-Digest.
• Signature-Input: See RFC for details on Signature-Input
• Signature: See WICG for details on Signature.
• Idempotency-Key: A unique key for the request to ensure idempotency (e.g., 60c72b2f9b1e8c001c8e4d3c). See IETF Idempotency for more details.

Payload

All webhook requests are sent as JSON payloads. The payload structure is documented in the Events section (See Webhook Payload for each event).

Payload of the entity.created event.

{
    "_id": "60c72b2f9b1e8c001c8e4d3b",
    "trigger": "user",
    "source": {
        "type": "user",
        "value": "60c72b2f9b1e8c006c8e3d3g",
        "label": [
            {
                "lang": "en",
                "value": "Generic User"
            }
        ]
    }
}

Security

All webhook requests are signed according to HTTP Message Signatures (RFC 9421) using HMAC-SHA256 with a per-webhook secret key. They also include a Content-Digest (RFC 9530) for body integrity.

Headers

• Content-Digest: A Structured Field dictionary mapping algorithm → digest (e.g., sha-256=:<base64>:) computed over the raw request body bytes.
• Signature-Input: Defines which components are covered by the signature (e.g., "@method" "@target-uri" "content-digest" "content-type" "x-webhook-timestamp"), plus params like keyid, created, and alg="hmac-sha256".
• Signature: Carries the signature value (HMAC) over the signature base reconstructed from Signature-Input.

We cover the following components in the signature:

• @method: The HTTP method (e.g., POST).
• @target-uri: The full request URI (e.g., https://example.com/webhook).
• content-digest: The digest of the request body. If the event has no data, this won't be included.
• content-type: The value of the Content-Type header (e.g., application/json).
• date: The value of the Date header

Verification

• Validate Content-Digest for sha-256 against the received body.
• Parse Signature-Input / Signature (Structured Fields) and build the signature base per the RFC.
• Resolve the key via keyid and verify HMAC-SHA256.
• Check created / expires (allow minimal clock skew) and deduplicate nonce / x-webhook-id for replay protection.

info

Since users are not allowed to create webhooks, you will receive the signing secret when we create the webhook for you.

Retries & timeouts

We treat delivery as successful if your endpoint returns any 2xx or 3xx within 10s.
Status codes 4xx are considered failures.
We retry on 408 and 5xx with exponential backoff, e.g.

Attempt	Delay
1	500–650 ms
2	1000–1150 ms
3	2000–2150 ms (final)

After the final attempt, the delivery is logged as failed.

Considerations

• Payload size: up to 256 KB per request.
• Rate: high volume may require batching or queuing on your side.