Receiver best practices

Follow these practices to build an endpoint that does not miss events, does not process them twice and cannot be fooled by forged requests.

Respond quickly, process later

BeepClock waits at most 10 seconds for a response. Store the event, respond with 2xx (for example 202 or 204) and do the actual work in the background, for example from a queue. Heavy processing inside the request risks a timeout, and every timeout causes a retry of an event you may already have handled.

Verify every request

Verify the signature on the raw body before you parse or trust the payload, compare signatures in constant time, and reject requests with an outdated t. Accept every v1 value in the header so that secret rotation does not interrupt deliveries.

Handle duplicates

Delivery is at least once. Keep the delivery IDs you have processed, for example in a table with a unique key, and skip a delivery whose ID you have already seen. Retries and resends always repeat the same ID and body.

Do not rely on order

Events can arrive out of order, especially after retries. When the order matters, for example when an employee is updated twice, compare occurredAt and keep the newest state.

Be tolerant of the payload

Ignore fields you do not know and treat missing fields as null. BeepClock can add new fields without changing apiVersion. If an event refers to an object that has since been deleted, data contains only id.

Use the right status codes

Situation	Respond with
Event stored	Any 2xx
Invalid or missing signature	401
Temporary problem on your side	5xx, or let the request time out. BeepClock retries.
The endpoint is permanently retired	410 Gone. BeepClock pauses the webhook at once.

Do not answer with a redirect: BeepClock does not follow redirects and counts them as failures.

Keep secrets secret

• Store the signing secret and any custom header values, for example an API token, in your secret store or environment variables, not in source code.
• Generate a new signing secret if the old one may have been exposed.
• Use HTTPS with a valid certificate. BeepClock sends only to https addresses.

Monitor the integration

• Check the delivery log after changes to your endpoint, and use Send test event after every deployment.
• Make sure the email that BeepClock sends when it pauses a webhook reaches someone who can act on it.
• After fixing an outage, resend the deliveries that failed.

Checklist

• https endpoint, publicly reachable, responds with 2xx within 10 seconds.
• X-BeepClock-Signature verified on the raw body with a constant-time comparison; the key is the whole whsec_… secret.
• Requests with an outdated t rejected (for example after 5 minutes).
• Several v1 values accepted, for secret rotation.
• Deliveries deduplicated by X-BeepClock-Delivery; processing is idempotent.
• No assumptions about delivery order; occurredAt used where order matters.
• Unknown fields ignored; missing fields treated as null.
• Fast 2xx and processing in the background; 410 only when the endpoint is permanently retired.