Getting Started with Webhooks

Webhooks tell your application when something changes in Crewsum, so you do not have to poll the API. When a record changes, Crewsum sends an HTTP POST request with a JSON body to a URL that you choose.

Use webhooks to keep another system in sync with Crewsum. For example, update your CRM when a client changes, or start payroll processing when a timesheet is submitted.

How webhooks work

1. An administrator creates a webhook in Crewsum. A webhook has a URL and a list of events to send to that URL.

2. Someone makes a change, in the Crewsum app or through the API.

3. Crewsum sends a signed POST request to the URL of every webhook that subscribes to that event. The body has two fields:

   {
     "event": "projects.created",
     "data": { "projects": [{ "id": "project-mno123pqr4567890", "name": "Warehouse Automation Rollout" }] }
   }

   The example is shortened. Each event page shows the full payload.

4. Your endpoint checks the signature, responds with 200, and processes the event.

Supported events

The event type is the event field of the body. Match it exactly. Most types are plural (clients.created), but the timesheet events are singular (timesheet.saved).

Resource	Event types
Clients	clients.created, clients.updated, clients.deleted
End customers	end-customers.created, end-customers.updated, end-customers.deleted
Projects	projects.created, projects.updated, projects.deleted
Contacts	project-contacts.created, project-contacts.updated, project-contacts.deleted
Tasks	tasks.created, tasks.updated, tasks.deleted
Project-contact associations	associations.created, associations.updated, associations.removed
Suppliers	suppliers.created, suppliers.updated, suppliers.deleted
Supplier contacts	supplier-contacts.created, supplier-contacts.updated, supplier-contacts.deleted
Users	users.created, users.updated, users.archived, users.deleted
Time entry	timesheet.saved, timesheet.submitted, timecards.reviewed, timesheet.deleted

The Contacts endpoints send project-contacts.* events. User groups and user assignments do not send events.

See Webhook Events for what triggers each event and which API endpoint sends it.

Before you start

• You must be an administrator in Crewsum to manage webhooks.
• Your endpoint must accept POST requests from the internet. Use an https:// URL.
• Your endpoint must read the raw request body to check the signature. Crewsum sends JSON but does not set Content-Type: application/json.

Know the delivery rules

Crewsum sends each event once and does not retry failed deliveries. Crewsum also waits for your response during the action that caused the event, so respond quickly. The webhook Enabled switch currently does not stop deliveries. Read Delivery before you go to production.

Next steps

Create a webhook Add a webhook in Crewsum and copy its key.

Validate signatures Check that each request comes from Crewsum.

Delivery Timing, responses, retries, and ordering.

Webhook events Every event type with an example payload.