Outbound webhooks

A webhook is a message your site sends to another service the moment something happens. HappenBoard Pro can send one when someone signs up, cancels, changes status, checks in or is deleted, so you can connect your events to Zapier, Make, n8n or your own CRM.

Webhooks need HappenBoard Pro. See what Pro adds.

Add a webhook

First, get an address to send to from the receiving service. In Zapier, for example, it is the URL of a Catch Hook trigger.

1. Go to HappenBoard → Integrations and click Configure on the Webhooks (Pro) card.
2. Click Add webhook.
3. Fill in a Label, such as “Zapier, new sign-ups”. It is only shown in your list.
4. Paste the address into Endpoint URL.
5. Leave Signing secret empty to have HappenBoard create one, or type your own.
6. Leave Active on.
7. Under Events, tick what to send (at least one).
8. Click Create webhook.

HappenBoard then shows the signing secret above the list. Copy it now if the receiving service checks signatures: it is never shown again.

Choose the events

The name in brackets is what the receiving service sees in the message.

Keep the signing secret safe

With the signing secret, the receiving service can check that a message really comes from your site. HappenBoard shows it only once: when the webhook is created, and again each time you replace it. After that, the edit form only shows its last four characters.

To replace it, click Edit on the webhook, then Generate a new secret. You can also type a new one in Signing secret and save. Messages are signed with the new secret at once, so give it to the receiving service straight away.

Test a webhook

Click Test on the webhook’s row. HappenBoard sends a test message (webhook.test) at once and tells you whether the receiver accepted it, or why not. A test works even when the webhook is off and is never retried.

How deliveries work

• Messages leave in the background, just after the event, so your visitors never wait. On a quiet site they leave the next time WordPress runs its scheduled tasks.
• The receiver has five seconds to answer with a success code.
• With no answer, or a temporary error, HappenBoard tries again 1, 4, 16, 64 and 256 minutes later: six attempts over about six hours. Any other refusal is final.
• Each row shows how the last delivery went: Last delivery succeeded, or Last delivery failed with the reason and the number of failures in a row.
• After 50 failed attempts in a row, HappenBoard switches the webhook off. Its row reads Paused and says why, and the site’s administration email address (Settings → General) receives an email “Webhook switched off”. Fix the receiver, then switch the webhook back on: the count starts again from zero.
• Switching a webhook off or deleting it also stops the deliveries still waiting.

Use an address HappenBoard accepts

The Endpoint URL must start with http:// or https:// and point to a public server on the internet, not to a private or local address. It must use port 80, 443 or 8080, or no port at all. HappenBoard checks this when you save and tells you what is wrong.

HappenBoard never follows a redirect, so paste the final address.

For developers: verify a request

Each request is a POST with a JSON body holding event, delivered_at, delivery_id and data, the details of the event. Two headers matter most:

• X-HappenBoard-Delivery stays the same on every retry. Use it to ignore duplicates.
• X-HappenBoard-Signature-V1 reads t=<timestamp>,v1=<signature>. The signature is the HMAC SHA-256 of the timestamp, a dot and the raw body, keyed with the signing secret.

Refuse a request whose timestamp is more than five minutes from your clock, so a captured request cannot be replayed:

parse_str( str_replace( ',', '&', $_SERVER['HTTP_X_HAPPENBOARD_SIGNATURE_V1'] ?? '' ), $sig );
$t  = $sig['t'] ?? '';
$ok = ctype_digit( $t ) && abs( time() - (int) $t ) <= 300
	&& hash_equals( hash_hmac( 'sha256', $t . '.' . file_get_contents( 'php://input' ), $secret ), $sig['v1'] ?? '' );

The older X-HappenBoard-Signature header (an HMAC of the body alone) is still sent for existing receivers. The hooks fired around each delivery are listed in Calendar sync, webhook and check-in hooks.

If something goes wrong

• The address is refused when you save: read the message. It is usually a private address or a port other than 80, 443 or 8080.
• The test fails with an HTTP error: check the address in the receiving service, then its signing secret.
• A webhook shows Paused: the receiver failed 50 times in a row. Fix it, then switch the webhook back on.
• Messages arrive late: they wait for WordPress scheduled tasks. See Health and maintenance.

Next steps

• Slack notifications: a readable message in a team channel instead of data for a system.
• WhatsApp notifications: message your attendees rather than another service.
• MailerPress automations: turn the same moments into email sequences.
• QR code check-in: the scans that send the check-in events.