Skip to main content

Set up a webhook

Add-on

Webhooks are an add-on that BeepClock activates for each account separately. If Webhooks does not appear in the menu, contact BeepClock at [email protected] to activate them. See Availability.

This guide takes you from an empty endpoint to a working webhook in a few minutes. You need an HTTPS endpoint that accepts POST requests; the signature verification page has a complete receiver in Node.js and C# that you can start from.

1. Prepare the endpoint​

The endpoint must:

  • use https and be reachable from the internet. Addresses in private networks (10.x, 192.168.x, localhost and similar) are rejected.
  • respond with any 2xx status within 10 seconds. Redirects are not followed.
Testing on your own computer

To try webhooks before you deploy the receiver, expose a local server through an HTTPS tunnel, for example ngrok or Cloudflare Tunnel, and use the tunnel's public address as the endpoint URL.

2. Create the webhook​

  1. Open Webhooks in the BeepClock menu and choose Add webhook.
  2. Enter a Name, for example the name of the receiving system, and the Endpoint URL.
  3. Select the Events to send. They are grouped into time entries, employees and devices; the event reference explains when each one is sent.
  4. Optionally add Custom headers that your endpoint expects, for example Authorization: Bearer …. A webhook can have up to 10 custom headers. Their values are stored encrypted and are not shown again.
  5. Choose Save.

3. Save the signing secret​

After saving, BeepClock shows the signing secret, a string that starts with whsec_. It is shown only once. Copy it and store it in your system's configuration, for example as the BEEPCLOCK_WEBHOOK_SECRET environment variable. Your endpoint uses it to verify that requests come from BeepClock.

If you lose the secret, choose Generate new signing secret in the webhook's menu. The previous secret keeps working for 24 hours, so you can rotate it without downtime.

4. Send a test event​

Open the webhook and choose Send test event. BeepClock immediately sends a signed webhook.test event and shows the HTTP status and response time returned by your endpoint.

A test event is sent once, is never retried and does not appear in the delivery log. You can send one while the webhook is paused, to check the endpoint before resuming.

5. Watch real deliveries​

Record a time entry on a recorder, or change an employee or a device, and open the webhook again. The delivery log lists every delivery from the last 30 days with its status, the number of attempts and the last response. Select a delivery to see each attempt with the HTTP status, duration and error, and the exact payload that was sent.

If a delivery failed, fix the endpoint and choose Resend delivery. BeepClock sends the same payload with the same delivery ID, so your system can recognise it. See Deliveries and retries for the full behaviour.

Managing webhooks​

From the webhook list and the webhook page you can:

ActionWhat it does
EditChange the name, URL, events or custom headers. Leave a custom header value empty to keep the saved one.
Pause sending / Resume sendingStop and restart deliveries. Events that happen while a webhook is paused are not sent later.
Generate new signing secretCreate a new secret. Both secrets sign requests for the next 24 hours.
Delete webhookRemove the webhook. Deliveries still waiting for a retry are not sent.

Next steps​