Skip to main content
SStandShare

Webhook Subscriptions

Admin

Webhook subscriptions allow you to receive real-time HTTP POST notifications whenever certain events happen in your StandShare organization. Instead of manually checking StandShare for updates, your external tools (Slack, Zapier, custom apps, etc.) can react instantly.

info

Webhooks are an advanced feature intended for integrations and automations. If you are not sure whether you need webhooks, you probably don't — StandShare's built-in notifications handle most use cases.

For a deeper explanation of how webhooks work, including delivery guarantees and signature verification, see Understanding Webhooks.

When to use webhooks​

  • Sync events to an external calendar — have new events and rosters automatically appear in Google Calendar or Slack as they are created in StandShare
  • Trigger Slack notifications — post automatic messages to your team's Slack channel when settlement completes or when workers are assigned to a shift
  • Feed data to a reporting tool — send attendance, settlement, or family data to a spreadsheet, BI dashboard, or data warehouse in real time
  • Automate workflow steps — trigger custom business logic when events happen (e.g., send a reminder email when a registration closes, or flag overdue payments)

Add a webhook subscription​

warning

Security: Only configure webhook endpoints that you control or trust. StandShare will POST sensitive event data to the URL you provide. Never use a URL from an untrusted source.

  1. Sign in as an Admin.
  2. Navigate to Settings → Org Settings.
  3. Select the Webhooks tab.
  4. Click Add webhook in the top-right corner.
  5. Enter a Name for this webhook (e.g., "Slack event notifications" or "Data warehouse sync").
  6. Enter the Endpoint URL — this is the HTTPS address where StandShare will send notifications. Your service (Zapier, Slack, custom server, etc.) will provide this URL.
    • Important: URLs must use https:// (not http://). StandShare enforces TLS encryption for all webhook traffic.
  7. Select which Events you want to subscribe to. You can subscribe to a single event type or select multiple. For example:
    • Select All events (wildcard) to receive notifications for every event in your organization
    • Or select specific event types like "Event created," "Attendance recorded," "Settlement committed," etc.
  8. Click Add Webhook.

StandShare will display your signing secret on a screen. Copy this secret now and store it securely — you will need it to verify webhook signatures on your endpoint. The secret is shown only once and cannot be retrieved later.

Once added, StandShare will immediately begin sending notifications to your endpoint whenever a subscribed event occurs.

Manage your webhooks​

View your subscriptions​

The webhook subscriptions list shows all active and paused webhooks for your organization:

  1. Go to Settings → Org Settings → Webhooks tab.
  2. You will see a table of all subscriptions with the following information:
    • Name — the webhook's display name
    • Status — whether the webhook is Active (sending), Paused (not sending), or Disabled (broken or manually disabled)
    • Endpoint URL — the destination where notifications are being sent
    • Events — how many event types are subscribed, or "All events" if the wildcard is selected
    • Last success — when the last successful delivery was sent
    • Last failure — if deliveries have failed, when the last failure occurred

If you have no webhooks configured yet, you will see an empty state with a link to add your first webhook.

Edit a webhook​

To change which events are subscribed to, the endpoint URL, or the webhook name:

  1. Go to Settings → Org Settings → Webhooks tab.
  2. Find the webhook in the list and click the Settings button.
  3. A detail panel opens. Click the Settings tab.
  4. Update the Name, Endpoint URL, or Events as needed.
  5. Click Save changes.

Pause or resume a webhook​

To temporarily stop sending notifications without deleting the webhook:

  1. Go to Settings → Org Settings → Webhooks tab.
  2. Find the webhook and click Settings.
  3. In the detail panel, click the Pause button. The webhook status changes to Paused and no more deliveries are sent.
  4. To resume, click the Resume button and the webhook returns to Active status.

Rotate the signing secret​

For security, you can generate a new signing secret at any time. The previous secret remains valid for 24 hours (grace period) to give your endpoint time to update:

  1. Go to Settings → Org Settings → Webhooks tab.
  2. Find the webhook and click Settings.
  3. In the detail panel, scroll down to the Signing secret section.
  4. Click Rotate secret.
  5. Confirm that you understand this action is not reversible (a second rotation will overwrite the 24-hour grace window).
  6. StandShare generates a new secret and displays it once. Copy the new secret now and update your endpoint's verification code.
  7. Your endpoint can verify signatures with either the new secret (current) or the previous secret (during the 24-hour grace period). After 24 hours, only the new secret will be accepted.
warning

Save the secret immediately. It is shown only once on creation and on rotation. After you dismiss the panel, you cannot retrieve it from StandShare. If you lose the secret, you must rotate again to generate a new one.

Delete a webhook​

To permanently remove a webhook and stop all deliveries:

  1. Go to Settings → Org Settings → Webhooks tab.
  2. Find the webhook in the list and click the Delete button (red button on the right).
  3. Or, click Settings on the webhook, scroll to the Danger zone section, and click Delete webhook.
  4. Confirm the deletion.

Important: Deleting a webhook stops all future deliveries immediately. All past delivery history for this webhook is permanently removed. This action cannot be undone.

Signing secret security best practices​

The signing secret is used to verify that webhook requests actually come from StandShare, not from an impostor. Treat it with the same care as a password.

Do:

  • Store securely — Keep the secret in your server's environment variables, secrets vault, or password manager. Do not commit it to version control.
  • Rotate periodically — Change the secret every 6–12 months, or whenever you suspect it has been compromised.
  • Verify every webhook — Always check the X-StandShare-Signature header on every incoming request. Reject unsigned or invalid requests.

Do not:

  • Share the secret — Do not paste the secret into Slack, email, or unencrypted chat.
  • Expose in logs — Configure your logging to redact the secret in case logs are inspected.
  • Hardcode in the client — Keep the secret on your backend only. Do not expose it in frontend code or API responses.

For instructions on how to verify webhook signatures, see Understanding Webhooks.

Troubleshooting failed deliveries​

If your webhook deliveries are failing:

  1. Check the endpoint URL — Verify you copied the URL exactly as provided by your integration service. A single incorrect character will cause deliveries to fail.

  2. Confirm the endpoint is publicly accessible — StandShare must be able to reach your endpoint over the internet. If your endpoint is behind a firewall, on a private network, or requires a VPN, deliveries will fail. Use a service like ngrok or a cloud hosting provider to make your endpoint publicly accessible for testing.

  3. Verify HTTPS — All webhook URLs must use https:// (not http://). StandShare will reject http:// URLs.

  4. Check the response time — StandShare waits up to 30 seconds for your endpoint to respond. If your endpoint takes longer, the delivery will time out and be retried. If you need more processing time, return a success response (2xx) immediately and handle the work in the background asynchronously.

  5. Return a success response — Your endpoint must return an HTTP status in the 2xx range (e.g., 200, 201, 204) to indicate successful delivery. Any 4xx or 5xx response will be treated as a delivery failure and StandShare will retry.

  6. Check for automatic retries — StandShare automatically retries failed deliveries with exponential backoff over several hours. If your endpoint was temporarily down, deliveries may succeed on the next retry without any action on your part. See Understanding Webhooks for full retry details.

  7. Verify the signing secret — If you rotated the secret recently, make sure your endpoint is checking against the correct secret. Both the current and previous secrets are accepted for 24 hours after rotation to allow for updates.

  8. Test your endpoint manually — Use a service like Postman or curl to send a test POST request to your endpoint with a sample webhook payload. This will help you debug whether the problem is with StandShare or your endpoint code.

If deliveries continue to fail after checking these items, verify that your endpoint is logging all incoming requests and errors. Examine those logs to see exactly what requests are coming in and what errors are occurring.

Next Steps​

  • Understanding Webhooks — how webhook delivery works, retry behavior, and security signatures
  • Webhook Event Types — full list of events you can subscribe to with payload details
  • API Keys — another way to connect external tools to your StandShare data