What is a webhook signature?
A webhook signature is a stamp added to each message a service sends to your web address, so you can check it really came from them and was not changed on the way.
In plain words
A wax seal on a letter tells you two things. The letter came from who it says, and nobody opened it. A webhook signature does the same job for the notes a service sends to your software.
Without one, anyone who guessed your web address could post a made-up event, such as "payment received", and your software might believe it. The signature lets your software tell the real from the fake.
It works with a shared secret. The service and you both know it. The service mixes the secret with the note and the time to make a short code. Your software does the same sum and compares. If the codes match, the note is genuine.
You do not need to do this by hand. If a developer builds your integration, ask them to check the signature. Many ready-made tools do it for you.
Think of it as checking the stamp on a parcel before you sign for it. A quick look keeps the records of your customers free from fake notes, and it costs you almost nothing.
How it works in Spaces
Every Spaces webhook delivery is signed. A signature header holds a timestamp and an HMAC-SHA256 code of the timestamp and the raw body, made with your secret. A second header holds the event id.
The secret is shown once, when you create the webhook. You can send a signed test event, see the past week of deliveries and send one again. A repeated delivery of the same event is not a second message.
Related terms
- Webhook: A webhook is a message one service sends automatically to another's web address the moment something happens, such as a new customer message arriving.
- Retry: A retry is trying the same thing again after it failed, usually after a short wait, in case the problem was only temporary.
- Safe to retry: Something is safe to retry, or idempotent, when doing it twice has the same result as doing it once, so a repeat never sends a second copy.
- Trigger: A trigger is something that happens, such as a customer sending a message, that wakes your AI agent so it can respond straight away.
FAQ
Do I have to check signatures?
It is strongly worth it. It is the way to know an event truly came from Spaces.
Where do I find the secret?
It is shown once when you create the webhook. Keep it somewhere safe.
Can I try it without a real event?
Yes. Spaces can send one signed example event to your address and show you what your server answered.
What does a repeated delivery mean?
It is the same event sent again, with the same event id, so your software can ignore it.
Useful next: API reference, Triggers, Security. Every term: the glossary.