Secure Your Webhook
Every webhook Celoxis sends comes with a security “stamp” (called a signature) so your receiving system can confirm the message genuinely came from Celoxis and wasn’t changed along the way. This page explains how that signature is created and how to check it.
What Celoxis sends with every request
Along with the message, Celoxis includes a few extra details in the request headers:
- A timestamp (X-Celoxis-Timestamp) — the exact time the message was signed.
- A signature (X-Celoxis-Signature) — the security stamp, created from your Secret and the message.
- A delivery ID (X-Celoxis-Delivery-Id) — a unique reference for that delivery, handy for your logs.
How the signature is created
- Celoxis takes the timestamp and the message body and joins them together.
- It then uses your Secret with a standard method called HMAC-SHA256 to turn that combined text into a unique signature. The same Secret and the same message always produce the same signature, but the signature can’t be reversed to reveal the Secret.
- That signature is sent along with the request.
How to check the request on your side
- Use the message exactly as it arrives. Don’t reformat or rebuild it first — even a small change will make the signature not match.
- Take the timestamp and the signature from the request headers.
- Recreate the signature yourself using the same HMAC-SHA256 method with your copy of the Secret.
- Compare the two signatures. If they match, the request is genuine — accept it. If they don’t, reject it.
- (Recommended) Also reject the request if the timestamp is too old (for example, more than 5 minutes), so an old message can’t be resent later. This is your choice — Celoxis doesn’t require it.
Keep your Secret private — anyone who has it could fake requests. If you generate a new Secret, update it on the receiving side too, or the old one stops working and requests will start being rejected. Both sides must always use the exact same Secret.