Webhooks send an event to another system each time something happens in SERVOS: a stay, a booking or an order is made, changed or cancelled, or a guest checks in. A door-lock system, a CRM or your own server can then react without asking SERVOS for changes. You set them up under Settings → Webhooks (owners and admins). How the receiving system reads events is in the webhooks API docs.
Adding an endpoint
An endpoint is a URL on the other system that receives events. Press Add endpoint and fill in:
- "Payload style": "Thin" events say what changed, and the other system fetches the rest with an admin API key that can read "Stays", "Bookings" or "Orders"; "Snapshot" events include the stay, booking or order itself, without the guest's name or contact details. Ask whoever runs the other system which one it expects.
- "Events": the events this endpoint receives.
- "Endpoint name (optional)", to tell endpoints apart.
- "Endpoint URL", an
https://address the other system gives you. It must be reachable from the internet. - "Description", if you like.
To change any of these later, choose Edit in the endpoint's menu. A new URL also receives the events still waiting to be sent.
The signing secret
Each endpoint has a signing secret that the other system uses to check an event really came from SERVOS. Press Reveal next to "Signing secret" on the endpoint's page and copy it to the other system. Treat it like a password.
SERVOS signs events as Standard Webhooks specifies. Tell whoever builds the other system: free libraries for most programming languages check the signature for them, and the webhooks API docs show how.
An endpoint's secret can't be changed. If it leaks, add a new endpoint with the same URL, payload style and events, give its secret to the other system, then delete the old one.
Testing and following deliveries
Send test event in the endpoint's menu sends a ping event, so you
can check the other system receives it. It's there while the endpoint is
enabled.
"Last 7 days" on the endpoint's page shows how many events were sent, how long the other system took to answer and how many failed; the list of endpoints shows the same for each. Every event sent to the endpoint is listed under "Event deliveries" with its status:
- "Pending": waiting to be sent, or to be tried again.
- "Sending": on its way.
- "Succeeded": the other system accepted it.
- "Failed": the other system refused it or couldn't be reached, every time, for nearly four days.
"Response" shows the HTTP status the other system answered with, or the error when it couldn't be reached. SERVOS tries again on its own, so a temporary outage needs nothing from you.
Send again sends an event that succeeded or failed once more: a failed one once the other system works again, or one it accepted but lost. It's there while the endpoint is enabled.
Pausing and deleting
Disable in the endpoint's menu pauses it. Events that were already waiting are sent once you Enable it again, but nothing that happens while it's disabled is sent. Delete in the same menu stops it for good, and drops the events still waiting.
Common questions
Does the other system get the guest's name or email? No. Events name the customer who booked only by an id, and leave out the guests registered on the stay. A system that needs the customer's details reads them through the API, with an admin key that can read "Customers" and "Customer data".
Why did the other system get the same event twice? SERVOS sends an event again when the other system doesn't accept it in time or answers with an error, and when someone presses Send again. Each event has an id that stays the same, so the other system can tell a repeat from a new event.
Which events are there? Stays: booked, changed, cancelled, checked in and checked out. Bookings: made, changed, cancelled, checked in and marked as a no-show. Orders: placed, changed and cancelled; payments and refunds aren't sent yet.