{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-api-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks deliver an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," to a URL you control when something happens in"," ","the platform, so you don't have to poll."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Configure them in the admin console under ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings → Integrations → Webhooks"]},":"," ","choose the events to subscribe to and supply a target URL."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The target URL ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," use HTTPS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authentication is optional: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["none"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP Basic"]},", configured per webhook."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Every delivery attempt is recorded in the webhook history for debugging."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payload","__idx":2},"children":["Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," with this JSON body:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The event code that fired."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ID of the affected entity."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["entity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Entity type, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_shift_user"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_endpoint"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full API endpoint to fetch the entity. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Empty string when the entity was deleted."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional context. Present only for some events."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"event_shift_user:update\",\n  \"id\": 84213,\n  \"entity\": \"event_shift_user\",\n  \"api_endpoint\": \"https://example.rosterfy.com/api/v2/event/912/shift/4471/user/84213\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The payload is deliberately thin — it tells you ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["what"]}," changed, not the full"," ","record. Follow ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_endpoint"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," to retrieve current state. That also"," ","means you always act on fresh data rather than on a payload that may have been"," ","queued or retried."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requests carry ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Content-Type: application/json"]}," and, where available, an"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Request-Id"]}," header you can use to correlate a delivery with its history entry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verifying-authenticity","__idx":3},"children":["Verifying authenticity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deliveries are not cryptographically signed."]}," There is no HMAC signature"," ","header. If you need assurance that a request genuinely originated from Rosterfy,"," ","your options today are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable HTTP Basic auth on the webhook and verify the credentials."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat the payload as untrusted and confirm state by calling ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_endpoint"]}," ","with your own authenticated token before acting."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The second is the stronger control, and we recommend it regardless: it protects"," ","you against spoofed, replayed, and out-of-order deliveries alike."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"available-events","__idx":4},"children":["Available events"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event code"},"children":["Event code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fires when"},"children":["Fires when"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user:register"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user registers"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user record is updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["user:delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user is deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An event is created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An event is updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_user:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user is added to an event, including via expression of interest"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_user:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An event user record is updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_user_activity:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An event user activity is submitted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_user_activity:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An event user activity is updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_shift:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A shift is created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_shift:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A shift is updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_shift_user:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user is assigned to a shift"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event_shift_user:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A shift user record is updated, including status changes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_offer_user:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user is added to a role offer"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_offer_user:update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A role offer user record is updated, including status changes"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["training_user:create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Training is assigned to a user"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["training_user:delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A training assignment is removed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["training:complete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A user completes training"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["form:process"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A form is submitted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report:generate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A report finishes generating"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*_shift_user:update"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["role_offer_user:update"]}," cover both general"," ","updates and status transitions — there is no separate status-changed event. Read"," ","the entity via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_endpoint"]}," to see the new status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"automation-triggered-webhooks","__idx":5},"children":["Automation-triggered webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Beyond the fixed list above, a webhook can be used as an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["action inside an"," ","Automation"]}," (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settings → Automations"]},"). There you define the trigger yourself,"," ","so the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," field carries the automation task you selected rather than one of"," ","the system codes above."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"user:checkpoint:update\",\n  \"id\": 55231,\n  \"entity\": \"user\",\n  \"api_endpoint\": \"https://example.rosterfy.com/api/v2/user/55231\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," is driven by your automation task, it is effectively"," ","customer-defined. This lets you react to anything the automation builder"," ","supports, well beyond the fixed event list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Design your receiver to tolerate an unrecognised ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," value rather than"," ","rejecting it — the fixed list can grow, and automation codes are open-ended."]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Payload","id":"payload","depth":2},{"value":"Verifying authenticity","id":"verifying-authenticity","depth":2},{"value":"Available events","id":"available-events","depth":2},{"value":"Automation-triggered webhooks","id":"automation-triggered-webhooks","depth":2}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-08-18T06:10:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/api-docs/guides/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}