Understanding Webhooks
Webhooks are how StandShare proactively notifies your other tools when something happens in your organization. Instead of a tool repeatedly asking StandShare "has anything changed?", StandShare sends a message to the tool the moment an event occurs.
This page explains the concepts behind webhook delivery so you can set up integrations with confidence and diagnose problems when they arise.
Push versus pull
Most data integrations work by pulling — a tool periodically asks StandShare for the latest data. This works, but it is slow (you only get updates as often as you check) and inefficient (most checks find nothing new).
Webhooks push — StandShare sends data to your tool the moment something happens, with no polling required. If an event is created at 2:14 PM, your external tool receives a notification at 2:14 PM.
This makes webhooks well-suited for time-sensitive workflows: posting to Slack when settlement completes, updating a calendar when an event is created, or triggering a report when a roster changes.
How delivery works
When a subscribed action occurs in StandShare — an event is created, a worker checks in, settlement runs — StandShare packages the relevant information into a notification and sends it as an HTTP POST request to the URL you configured.
Your endpoint (the URL you provided) receives the notification and should return a success response to confirm it was received. StandShare considers a delivery successful when the endpoint returns any response in the 200–299 range within 30 seconds.
Delivery is not instantaneous. There is typically a small delay of a few seconds between when the action occurs in StandShare and when the notification arrives at your endpoint. For most use cases this is unnoticeable. It is not suitable for applications that require sub-second synchronization.
At-least-once delivery and retries
StandShare guarantees at-least-once delivery: if a notification fails to reach your endpoint, StandShare will try again.
Retries use exponential backoff — the delay between retry attempts grows with each failure:
| Attempt | Delay before retry |
|---|---|
| 1st retry | 30 seconds |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 8 hours |
After all retry attempts are exhausted, the delivery is marked as permanently failed. It will appear in the delivery log with a failed status.
Because delivery is at-least-once — not exactly-once — your endpoint may occasionally receive the same notification more than once. This is rare but can happen if StandShare retries a delivery that actually succeeded but timed out before the response arrived. Design your integration to handle duplicate notifications gracefully. The id field on every payload is unique per notification and can be used to detect and discard duplicates.
Deduplicating with the delivery identifier
Every delivery carries the same stable identifier in two places: the id field inside the payload, and the X-StandShare-Delivery response header. The header lets your endpoint recognize a repeat before it even parses the body.
The reliable way to handle duplicates is to make your processing idempotent on that identifier:
- Read the delivery identifier (from the header or the payload
id). - If you have already processed it, acknowledge with a
200and stop. - Otherwise, process the notification and record the identifier as handled.
When StandShare retries a delivery — whether after a timeout, a transient network error, or an internal failover — the retried request carries the same identifier as the original. Deduplicating on it therefore collapses every retry of one event into a single action, no matter how many times it arrives.
One thing deduplication can't collapse: if the same real-world action is itself retried at the source — for example, a user resubmits a form after seeing an error — that produces two genuinely distinct events with two different identifiers. Treating them as two events is correct; they are two events. This is inherent to any at-least-once delivery system.
What happens during a database failover
StandShare runs on a managed database that can briefly fail over to a standby — for routine maintenance or automatic recovery. The webhook system is designed so that a failover occurring mid-delivery never loses or corrupts a notification.
If a failover interrupts a delivery in the narrow window between "sent to your endpoint" and "recorded as sent," StandShare simply re-attempts it — with the same delivery identifier as before. The practical effect for you is the one you are already prepared for: you may occasionally see a duplicate during these windows, and your identifier-based deduplication handles it transparently. There is nothing special to configure or handle for failovers.
Security: verifying deliveries
Every notification StandShare sends includes a signature header. This is a short string of characters that your endpoint can use to confirm the message genuinely came from StandShare and was not tampered with in transit.
The signature is computed using a secret key that only StandShare and your endpoint know. When your endpoint receives a delivery, it can recompute the signature using the same secret and compare it to the value in the header. If they match, the message is authentic.
If you do not verify signatures, your endpoint will accept any request sent to it — including ones not from StandShare. Always validate the signature before acting on a webhook delivery.
Your external tool or developer will handle signature verification. The details of how to implement it depend on the tool you are using. Documentation for the signature format is available in the StandShare platform API reference.
Payload structure
Every webhook delivery has the same outer structure, regardless of which event triggered it:
id— a unique identifier for this specific deliverytype— the event type that triggered the delivery (for example,event.createdorattendance.checked_in)created_at— the timestamp when the notification was generateddata— the details of what happened, specific to the event type
The data field contains different fields depending on the event type. For a full list of event types and their payload fields, see Webhook Event Types.
When building an integration, write your code to handle fields it does not recognize gracefully. New fields may be added to payloads in future releases. An integration that rejects unknown fields will break when the payload evolves.
Common use cases
Notify a Slack channel when a new event is created
Configure a webhook for the event.created event type. When an event is created in StandShare, the notification arrives in your Slack integration, which formats and posts a message to the channel of your choice.
Sync attendance data to an external spreadsheet
Subscribe to attendance.checked_in and attendance.checked_out. Each check-in and check-out sends a notification to your integration, which appends a row to a spreadsheet in real time.
Trigger a workflow when settlement completes
Subscribe to event.settled. When settlement runs for an event, your workflow tool receives the notification and can kick off downstream steps — generating a report, sending a summary email, or updating a dashboard.
Limitations
- Your endpoint must be publicly accessible. StandShare sends notifications over the internet. An endpoint on a private network or behind a firewall that blocks inbound requests will not receive deliveries.
- Delivery is not instant. Notifications arrive within a few seconds of the triggering action, not immediately.
- Your endpoint must respond within 30 seconds. If your system needs time to process the notification, respond with a success code immediately and process the data in the background.
- Retry attempts have a limit. After all retries are exhausted, StandShare stops attempting delivery. Permanently failed deliveries appear in the delivery log.
- At-least-once delivery. Duplicates are rare but possible. Use the
idfield to deduplicate if your integration requires exactly-once processing.
Next Steps
- Configure Webhooks — set up a webhook endpoint in your organization settings
- Webhook Event Types — full list of supported events with payload details and an example
- API Keys — scoped API keys for tools that pull data from StandShare on demand