Xilnex Event Hub Webhook Receiver Guide

Xilnex Event Hub Webhook Receiver Guide

Introduction

A webhook receiver is the endpoint on your system that accepts event notifications sent by Xilnex Event Hub. This guide explains how to build a receiver that is secure, reliable, and fast enough to avoid retries.

It covers payload versioning, signature validation, duplicate prevention, and response timing requirements.

Note: Your receiver must respond to each webhook call within 10 seconds. Otherwise, Xilnex treats the call as timed out and starts retries.

Terminology

TermDescription
Webhook receiverThe endpoint on your system that listens for and processes webhook calls from Xilnex Event Hub. Also called the webhook listener.
Shared secretA key you configure in the Xilnex Portal when you manage the webhook configuration. Your receiver uses it to validate request signatures.
SignatureA hash of the request body, sent in the xilnex-webhook-signature header. It proves the call came from a trusted source.
HMAC SHA-256The hashing algorithm used to create and validate the signature.
Webhook job IDAn identifier sent in the xilnex-webhook-webhookjobid header. It stays the same across retries, so your receiver uses it to detect duplicate calls.

Request Headers

Each webhook call from Xilnex includes the following headers that your receiver must read.

NameData TypeRequiredDescription
xilnex-webhook-signatureString (hex-encoded)YesThe HMAC SHA-256 hash of the raw request body, signed with the shared secret. Use it to validate the request.
xilnex-webhook-webhookjobidStringYesThe webhook job identifier. A retry carries the same value as the original call, so use it as an idempotency key.

Implementation Recommendations

Follow these recommendations when you build your webhook receiver.

Payload Versioning and Backward Compatibility

When the structure of the webhook payload changes, create a new endpoint on your receiver. This keeps existing integrations working on the old payload structure.

Request Authentication via Signature Validation

Validate the request signature on every call. This confirms the webhook call originates from a trusted source.

Use HMAC with SHA-256 to hash the request body with the shared secret. Then compare the result with the xilnex-webhook-signature header value, using a secure comparison function. See Validate the Request Signature below for the steps.

Duplicate Webhook Prevention

A retry carries the same xilnex-webhook-webhookjobid as the original call. Treat it as an idempotency key and check it on every call.

  • On a duplicate: return the same 2xx response as the original call, without re-executing any side effects. This covers the common case where your original 2xx response was lost in transit and Xilnex retried.
Note: Do not reject a duplicate with a non-2xx response. Xilnex treats any non-2xx response as a failure and keeps retrying until the job is marked as failed.

Response Timing Requirements

RequirementDetail
Initial responseRespond to each webhook call within 10 seconds to prevent an initial timeout.
RetriesIf the first call fails or times out, Xilnex retries up to 3 times. Each retry has a 100-second HTTP timeout. The wait between retries grows quadratically (attempt2): 1, 4, then 9 minutes. See the schedule below.
ProcessingProcess requests efficiently. Handle work asynchronously if needed, so the response is not delayed.
Success responseAny HTTP status code from 200 to 299 counts as a successful delivery. Any other status code counts as a failure and triggers a retry.

Retry schedule

AttemptWait Before AttemptHTTP Timeout
First callNone10 seconds
Retry 11 minute100 seconds
Retry 24 minutes100 seconds
Retry 39 minutes100 seconds

If the last retry also fails, Xilnex marks the webhook job as failed.

Validate the Request Signature

Warning: If your receiver skips signature validation, it cannot confirm that a call came from Xilnex. Keep the shared secret private and share it only with the team that maintains the receiver.
  1. Retrieve the signature from the xilnex-webhook-signature request header.
  2. Extract the raw request body.
  3. Hash the request body with the HMAC SHA-256 algorithm, using the shared secret as the key, and encode the result as a hex string.
  4. Compare the result with the signature from the header, using a secure comparison function.

If the values match, the request is valid. If they do not match, return 401 Unauthorized with a minimal response body.

If the Signature Does Not Match

You configure the signature secret in the Xilnex Portal. A mismatch usually means either the Portal secret or your receiver's local verification secret is wrong or out of date. Check both, and correct whichever is wrong.

Note: Xilnex computes the signature once, when it creates the webhook job, and reuses it on every retry. Where you make the fix decides whether in-flight retries recover.
Where You Fix the SecretEffect on In-Flight Retries
Receiver side (local verification secret updated to match the Portal)In-flight retries succeed.
Xilnex Portal (secret updated in the Portal)In-flight retries still fail, because they carry the signature generated from the old secret. They keep retrying until the job is marked as failed.
Info: You configure the shared secret in the Xilnex Portal when you manage the webhook configuration. For setup steps, see Integrating with Xilnex: Event Triggers & Webhook Configuration.