Skip to main content

Webhook Endpoints

Each organization can configure multiple endpoints to receive event notifications.

Endpoint Fields​

FieldDescription
URLHTTPS address that will receive notifications
DescriptionEndpoint description (max 255 characters)
EventsList of subscribed event types
SecretHMAC-SHA256 key for signature validation
ActiveWhether the endpoint is enabled

Creating an Endpoint​

Upon creation, the system automatically generates a secret (whsec_...) that is shown only at creation time. Store it securely — it is required to validate webhook signatures.

Webhook Signature​

Every delivery carries the Kobana standard headers (X-Kobana-App, X-Kobana-Environment, X-Kobana-Webhook-Id, X-Kobana-Event, X-Kobana-Event-Id, X-Kobana-Delivery-Id, X-Kobana-Timestamp, X-Kobana-Signature) plus the webhook-id / webhook-timestamp / webhook-signature trio in the Standard Webhooks layout:

X-Kobana-Signature: v1,<base64(HMAC_SHA256(key, delivery_id + "." + timestamp + "." + raw_body))>

Verification​

  1. Read webhook-id, webhook-timestamp and webhook-signature
  2. Reject if the timestamp is more than 5 minutes away from your clock
  3. Rebuild delivery_id.timestamp.raw_body and compute HMAC-SHA256 with the key (base64-decoded secret without the whsec_ prefix)
  4. Compare with each v1, token of the header in constant time

The full algorithm, with Node.js and Python examples, is in API Reference — Webhooks. The legacy X-Signature header (t=<unix>,v1=<hex>) is still sent, deprecated.

Secret Rotation​

When you suspect the secret has been compromised, use secret rotation. A new secret is generated and the previous one is invalidated immediately.

Webhook Test​

Send a test payload to verify that the endpoint is configured correctly. The result includes the HTTP status and the received response.

Automatic Deactivation​

After 10 consecutive delivery failures, the endpoint is automatically deactivated. To reactivate, fix the issue and update the endpoint to active.

SSRF Protection​

URLs are validated to reject private IPs and localhost, preventing Server-Side Request Forgery attacks.