Creating a Webhook

A webhook sends the events you choose to a URL on your server. This page shows how to create one in the Crewsum app and get the key that you use to validate signatures.

Before you start

• You must be an administrator in Crewsum. Other roles cannot open the Developer pages.
• Have the URL of your endpoint ready. It must accept POST requests from the internet. Use an https:// URL.

Create the webhook

1. In Crewsum, go to Developer > Webhooks (app.crewsum.com/developer/webhooks). The Webhooks page lists your webhooks.

   

2. Click Add Webhook. The New Webhook panel opens.

3. Fill in the form:

   • Enabled: This switch is off by default. At present it has no effect on delivery (see the note below).
   • Label: A name that helps you recognize the webhook, such as “Operations event bus”.
   • URL: The URL that receives events, such as https://example.com/crewsum/events.
   • Events: Select at least one event. Each event shows its name and its event type, such as Timesheet Submitted and timesheet.submitted. Use Search events to filter the list, and the Selected Events tab to review your choices.

   

4. Click Create Webhook. Crewsum shows “Successfully created webhook” and closes the panel.

Crewsum starts to send the selected events to the URL right away.

The Enabled switch does not stop deliveries

Crewsum currently sends events to a webhook whether Enabled is on or off. Do not create a webhook for a URL that is not ready to receive events. To stop deliveries, delete the webhook. See Delivery.

Copy the Webhook Key

Crewsum does not show the key when you create the webhook. Open the webhook again to get it.

1. On the Webhooks page, click the row menu (…) for your webhook, and then click Edit webhook.

   

2. On the Edit Webhook panel, find Your Webhook Key and click the copy button next to the key.

   

3. Store the key as a secret on your server, for example in the CREWSUM_WEBHOOK_KEY environment variable.

Crewsum never sends the key in a request. Your endpoint uses it to check the x-crewsum-signature header. See Validating Webhook Signatures.

Send a test event

Use a test event to check that your endpoint is reachable and validates signatures.

• On the Webhooks page, click the row menu (…) and then Send test, or
• On the Edit Webhook panel, click Send Event.

Crewsum sends a signed request with the body {"event":"debug","data":{"message":"Debug Event"}}. The message “Successfully sent debug event to webhook” means only that Crewsum sent the request. Check your endpoint’s logs to confirm that it accepted the request. You can send 10 test events per minute.

Change or rotate the key

To change the label, URL, or events, open the webhook with Edit webhook, make your changes, and click Update Webhook.

To rotate the key, click Regenerate Key on the Edit Webhook panel, and then click Regenerate Key in the Regenerate Webhook Secret dialog. The old key stops working immediately: the next request is signed with the new key. Copy the new key and update your endpoint right away.

Delete a webhook

Click the row menu (…) and then Delete webhook. In the Delete Webhook dialog, click Delete Webhook. Crewsum stops sending events to that URL.