Setting up webhooks

With an API key, another program fetches your data whenever it needs it. With a webhook it is the other way round: we send a message to an address of yours the moment something happens.

That saves waiting. An order that comes in at a quarter past eight is in your bookkeeping at a quarter past eight — not on the next round, an hour later.

What customers use it for:

• every sale straight into the bookkeeping or into their own database;
• a small screen at the entrance showing who just came in;
• a message in a group chat as soon as a guided tour sells out;
• their own e-mail or text message to the buyer, on top of ours.

This article is the guide to the screen, step by step. If you first want to know what a webhook is and whether you need one, read Webhooks.

Good to know: webhooks belong to the same plan as the API. On a smaller plan API access is not in your menu; if you do end up on the screen, you see an explanation and a To Subscription button.

Where to go

Open Settings → API access in the left-hand menu and click the Webhooks tab at the top. Only the Owner role sees this screen.

You will see three blocks: We call you (explanation), New destination (the form) and Destinations (what already exists).

What you need

One thing, and it has to exist before you start: an address on your own server that can receive messages. That is a bit of programming on your side — your web developer or your bookkeeping software will know what you mean by "an endpoint for webhooks".

Three requirements:

1. It must be https. We refuse a plain http address: buyer data travels over that line.
2. It must be reachable from the outside. An address inside your own office network (something with 192.168. or 10.) we cannot reach, and we refuse it as well.
3. It must answer quickly. We wait ten seconds. If processing takes longer, let your server say "ok" straight away and do the work afterwards.

Adding a destination

Step 1. Fill in the address. In the first field (https://...), the full address we may send to, for example https://bookkeeping.mycompany.com/webhooks/tickets.

Step 2. Say what it is for. The second field (What is this for?) is not required, but handy. "Our bookkeeping", "screen at the register". Once you have three, you will know which is which.

Step 3. Tick what we may notify you about. The list is under What should we tell you about?. This is the most important choice. Only tick what you actually process: every message you do not use is work for your server and noise in your log. At least one box must be ticked; a destination without messages would never receive anything.

Message	When it goes out
Order created	An order has come into being (a shopping basket does not count).
Order paid	The money has arrived.
Order cancelled	The order was cancelled or expired.
Order refunded	A full or partial refund happened.
Ticket issued	A ticket has been issued.
Ticket scanned	There was a scan at the entrance — including a refused one.
Ticket voided	A ticket was voided or refunded.
Time slot sold out	A time slot is full.
Time slot free again	There is room again in a full time slot.
Gift voucher issued	A voucher has been sold.
Gift voucher redeemed	An amount was deducted from a voucher.
Pass issued	An annual pass has been created.
Register session closed	A cash drawer has been counted and closed.
Invoice issued	An invoice or credit note was created for a buyer.

Step 4 (optional). Test destination. If the address points to a test environment, tick Test destination (only receives test events). More on that under "A test destination" below.

Step 5. Click Add destination.

You can have up to twenty destinations. If you already have twenty, delete one first.

You see the secret only once

Right afterwards a secret appears: a long string starting with whsec_.

Copy it now and pass it on to whoever builds the connection. Refresh the page or switch tabs and it is gone.

With that secret we sign every message we send to your address. Your server can use it to check that the message really comes from us and not from someone who picked up your address somewhere. That is not a luxury: without that check your endpoint is an open door where anyone can push orders through.

Lost the secret? Click New secret. You get a new one straight away and the old one stops working from that moment — so do not forget to replace it on the other side as well.

For whoever builds the connection, the developer portal explains exactly how to recompute that signature, with examples in PHP, JavaScript and Python. Through the API they can also request a signed example message to test their own code against, without having to make a sale first.

Testing without a sale

Click Test message next to a destination. We then send a single message of the kind test.ping — no real data, just a signal.

The message log opens right below it, so you can see what your server replied. If it says Delivered, it works. If it shows an error code, you know where to look. A test message is also sent to a destination that is switched off.

The message log

Click Messages next to a destination. You see the last fifty messages, and per message:

• what kind it was and when it went out;
• what your server returned (the number is the http status; 200 means "ok");
• how many times we tried;
• how it stands: Delivered, On the way (we are still trying) or Not delivered.

If a message has not arrived, you can offer the same message again with Try again. Handy after you have fixed an outage on your side.

Messages are kept for thirty days. After that they are cleaned up: the log is there to find a problem, not as an archive.

What happens when your server is down

We do not give up immediately. If a message does not arrive, we try six more times, with increasingly long intervals: after a minute, five minutes, half an hour, two hours, twelve hours and a day. Together that is well over a day and a half.

If it still does not work:

• the destination gets the mark Not getting through;
• you get one e-mail. It goes to your organisation's Contact e-mail, or to the Billing address (email) if the first is empty (both under Settings → Organisation, Contact tab);
• the destination stays on. Later events are offered again, and as soon as something arrives the mark disappears.

You get at most one such e-mail per day per destination. A server that is down for a weekend therefore does not produce a hundred e-mails.

A test destination

Tick Test destination when creating one if the address points to a test environment. Such a destination only receives test events — what happens to the test orders of a test key — and never real sales. It carries the Test mark in the list. Conversely, an ordinary destination never receives anything from a test order.

That separation is strict, and deliberately so: a test server that accidentally processes a real order sends a confirmation to a real buyer.

Switching off or deleting

Turn off stops the deliveries but keeps the destination, with its secret and its message log; it gets the Off mark. Handy during maintenance on your side. Click Turn on again and it runs once more.

Delete removes the destination and its message log. That cannot be undone; a new destination gets a new secret.

There is a third case: if your server ever answers with the code 410, we switch the destination off ourselves. That code literally means "this address no longer exists", and then knocking on would be impolite. The same happens when the address has since come to point to an internal network. Click Turn on as soon as it is sorted out.

Three tips for whoever builds the connection

1. Answer first, process afterwards. Say "ok" immediately and do the real work in the background. Otherwise you run into our ten seconds.
2. Process idempotently. Every message carries its own number (the Idempotency-Key). If the same number arrives twice, do nothing. We retry when in doubt, and a double booking is worse than a double log line.
3. Do not rely on the order. Two messages can overtake each other when the first one is repeated. Look at the time in the message and at its content, not at the order of arrival.

Read on

• Webhooks — what a webhook is and when you need one, without technical terms.
• Creating an API key — the other tab of this screen.
• The developer portal — for whoever builds the connection.