workers first
IndustriesPricingSecurityFor ProvidersHow It Works
Sign InGet started freeBook a demo

Guides

  • Introduction
  • Authentication
  • Errors
  • Rate limits
  • Idempotency
  • Pagination
  • Scopes

API Reference

  • Organization
  • Members
  • Customers
  • Sites
  • Shifts
  • timesheets
  • invoices
  • Bookings
  • Webhooks

Webhooks

  • Events & signatures

API Reference

Webhooks

Register webhook endpoints, manage signing secrets, and inspect deliveries.

Workers First

The all-in-one platform for organizations to manage their workforce, operations, and the people they serve.

support@keepworkersfirst.org

For Organizations

  • Book a Demo
  • Pricing
  • Security
  • Industries
  • Developers

For Providers

  • Join as Provider
  • Learn More

For Families

  • Create Account
  • Learn More

Company

  • About Us
  • Contact
© 2026 Workers First. All rights reserved.
Privacy PolicyTerms of ServiceAccessibility
GET/v1/webhook-endpoints

List webhook endpoints

Returns the webhook endpoints configured for your organization in this key’s mode.

Scope: webhooks:read

Request

curl -X GET "https://keepworkersfirst.org/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "data": [
    {
      "id": "aa11bb22-1111-4c33-8d44-e55f66a77b88",
      "url": "https://example.com/webhooks",
      "description": "Production receiver",
      "mode": "live",
      "enabled": true,
      "events": [
        "member.created",
        "member.verified"
      ],
      "secret_preview": "whsec_…a1b2",
      "consecutive_failures": 0,
      "disabled_at": null,
      "disabled_reason": null,
      "last_delivery_at": null,
      "last_success_at": null,
      "created_at": "2026-07-01T10:00:00+00:00",
      "updated_at": "2026-07-01T10:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
POST/v1/webhook-endpoints

Create a webhook endpoint

Registers a webhook endpoint. The signing secret is returned once in the response. Subscribe with an array of event types or ["*"] for all.

Scope: webhooks:write

Body parameters

urlrequiredstring

HTTPS URL to receive events.

descriptionstring
eventsrequiredstring[]

Event types to subscribe to, or ["*"] for all.

Request

curl -X POST "https://keepworkersfirst.org/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks","events":["member.created"]}'

Response · 201

{
  "id": "aa11bb22-1111-4c33-8d44-e55f66a77b88",
  "url": "https://example.com/webhooks",
  "description": "Production receiver",
  "mode": "live",
  "enabled": true,
  "events": [
    "member.created",
    "member.verified"
  ],
  "secret_preview": "whsec_…a1b2",
  "consecutive_failures": 0,
  "disabled_at": null,
  "disabled_reason": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-07-01T10:00:00+00:00",
  "updated_at": "2026-07-01T10:00:00+00:00",
  "secret": "whsec_examplesecretvalue"
}
GET/v1/webhook-endpoints/{id}

Get a webhook endpoint

Returns a single webhook endpoint by id.

Scope: webhooks:read

Path parameters

idrequiredstring (uuid)

Webhook endpoint id.

Request

curl -X GET "https://keepworkersfirst.org/api/v1/webhook-endpoints/aa11bb22-1111-4c33-8d44-e55f66a77b88" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "id": "aa11bb22-1111-4c33-8d44-e55f66a77b88",
  "url": "https://example.com/webhooks",
  "description": "Production receiver",
  "mode": "live",
  "enabled": true,
  "events": [
    "member.created",
    "member.verified"
  ],
  "secret_preview": "whsec_…a1b2",
  "consecutive_failures": 0,
  "disabled_at": null,
  "disabled_reason": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-07-01T10:00:00+00:00",
  "updated_at": "2026-07-01T10:00:00+00:00"
}
PATCH/v1/webhook-endpoints/{id}

Update a webhook endpoint

Updates a webhook endpoint’s URL, description, subscribed events, or enabled state. Re-enabling clears the auto-disable state.

Scope: webhooks:write

Path parameters

idrequiredstring (uuid)

Webhook endpoint id.

Body parameters

urlstring
descriptionstring | null
eventsstring[]
enabledboolean

Request

Response · 200

DELETE/v1/webhook-endpoints/{id}

Delete a webhook endpoint

Permanently deletes a webhook endpoint and its delivery history.

Scope: webhooks:write

Path parameters

idrequiredstring (uuid)

Webhook endpoint id.

Request

curl -X DELETE "https://keepworkersfirst.org/api/v1/webhook-endpoints/aa11bb22-1111-4c33-8d44-e55f66a77b88" \
  -H "Authorization: Bearer $API_KEY"

Response · 204

{}
POST/v1/webhook-endpoints/{id}/roll-secret

Roll a webhook signing secret

Generates a new signing secret and returns it once. The previous secret keeps signing for 24 hours so receivers can roll over without missing events.

Scope: webhooks:write

Path parameters

idrequiredstring (uuid)

Webhook endpoint id.

Request

curl -X POST "https://keepworkersfirst.org/api/v1/webhook-endpoints/aa11bb22-1111-4c33-8d44-e55f66a77b88/roll-secret" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "secret": "whsec_newexamplesecret"
}
POST/v1/webhook-endpoints/{id}/test

Send a test event

Sends a single test delivery of a real event type’s example payload (marked with X-Webhook-Test: true) and returns the immediate result.

Scope: webhooks:write

Path parameters

idrequiredstring (uuid)

Webhook endpoint id.

Body parameters

event_typestring

Event type to send (defaults to a subscribed one).

Request

curl -X POST "https://keepworkersfirst.org/api/v1/webhook-endpoints/aa11bb22-1111-4c33-8d44-e55f66a77b88/test" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"member.created"}'

Response · 200

{
  "delivery_id": "bb22cc33-2222-4d44-9e55-f66a77b88c99",
  "ok": true,
  "response_status": 200,
  "duration_ms": 142
}
GET/v1/webhook-deliveries

List webhook deliveries

Returns recent webhook delivery attempts for your organization in this key’s mode. Filter by endpoint, status, or event type.

Scope: webhooks:read

Query parameters

endpoint_idstring (uuid)
statusenum

pendingprocessingdeliveredfaileddead

event_typestring
limitinteger

Request

curl -X GET "https://keepworkersfirst.org/api/v1/webhook-deliveries" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

POST/v1/webhook-deliveries/{id}/redeliver

Redeliver a webhook delivery

Queues a fresh delivery of a previously-attempted event (same envelope id, so receivers can dedupe). Returns the new delivery id.

Scope: webhooks:write

Path parameters

idrequiredstring (uuid)

Webhook delivery id.

Request

curl -X POST "https://keepworkersfirst.org/api/v1/webhook-deliveries/bb22cc33-2222-4d44-9e55-f66a77b88c99/redeliver" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "delivery_id": "cc33dd44-3333-4e55-8f66-a77b88c99d00"
}
GET/v1/webhook-events

List available webhook events

Returns the catalog of event types you can subscribe to, filtered to your organization’s active modules.

Scope: webhooks:read

Request

curl -X GET "https://keepworkersfirst.org/api/v1/webhook-events" \
  -H "Authorization: Bearer $API_KEY"

Response · 200

{
  "data": [
    {
      "type": "member.created",
      "description": "A member was created.",
      "module_gate": "members"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
{
  "id": "aa11bb22-1111-4c33-8d44-e55f66a77b88",
  "url": "https://example.com/webhooks",
  "description": "Production receiver",
  "mode": "live",
  "enabled": false,
  "events": [
    "member.created",
    "member.verified"
  ],
  "secret_preview": "whsec_…a1b2",
  "consecutive_failures": 0,
  "disabled_at": null,
  "disabled_reason": null,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-07-01T10:00:00+00:00",
  "updated_at": "2026-07-01T10:00:00+00:00"
}
{
  "data": [
    {
      "id": "bb22cc33-2222-4d44-9e55-f66a77b88c99",
      "endpoint_id": "aa11bb22-1111-4c33-8d44-e55f66a77b88",
      "event_id": "evt_9f1b6e9e11114222",
      "event_type": "member.created",
      "mode": "live",
      "status": "delivered",
      "attempts": 1,
      "last_response_status": 200,
      "last_error": null,
      "redelivery_of": null,
      "delivered_at": "2026-07-01T10:00:03+00:00",
      "created_at": "2026-07-01T10:00:02+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
curl -X PATCH "https://keepworkersfirst.org/api/v1/webhook-endpoints/aa11bb22-1111-4c33-8d44-e55f66a77b88" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'