Webhooks

Overview

This guide provides developers with the instructions on how to implement and manage webhooks events and subscriptions.

Supported Event Types

user_created
user_updated
user_document_created
task_completed

Creating a Webhook Subscription

A subscription is required in order to start receiving event notifications. Make a POST request to:

/api/v1/webhook_subscriptions

Request Body

JSON payload with the following attributes:

Field	Type	Description
`event_type`	string	The type that will trigger a webhook
`target_url`	string	url endpoint that will receive the event

Scope

Every webhook subscription applies to all events of the specified type across your entire private label and its associated companies.

Managing Subscriptions

The following endpoints are used to manage subscriptions:

### Update

PUT /api/v1/webhook_subscriptions/:webhook_subscription_id
PATCH /api/v1/webhook_subscriptions/:webhook_subscription_id

### Delete

DELETE /api/v1/webhook_subscriptions/:webhook_subscription_id

### List

GET /api/v1/webhook_subscriptions

Example payloads

`task_completed`

{
  "event_type": "task_completed",
  "payload": {
    "available_at": null,
    "completed_at": null,
    "created_at": "2025-02-26T15:14:54.970Z",
    "description": "Please complete this task ASAP",
    "display_description": null,
    "display_name": null,
    "due_at": null,
    "name": "Very Important Task",
    "order": null,
    "updated_at": "2025-02-26T15:14:54.970Z",
    "status": "complete",
    "task_type": "to_do",
    "assigned_user_id": "1",
    "company_id": "1",
    "completed_by_user_id": "1",
    "created_by_user_id": "1",
    "id": "1",
    "step_id": null,
    "target_user_id": "1",
    "target_user_name": "Joe Doe",
    "task_data": {},
    "workflow_id": ""
  }
}

`user_created`

{
  "event_type": "user_created",
  "payload": {
    "admin": false,
    "compensation_type": "hourly",
    "created_at": "2025-05-06T18:11:15.676Z",
    "employment_type": null,
    "first_login_at": "2025-04-24T12:13:59.543Z",
    "job_title": "Community-Services Coordinator",
    "last_login_at": "2025-05-04T03:46:58.148Z",
    "last_name": "Murazik",
    "legal_first_name": "Lewis",
    "middle_name": null,
    "pay_period": "bi_monthly",
    "phone": "+919174654447",
    "preferred_first_name": null,
    "signed_up_at": "2025-04-23T11:59:19.000Z",
    "start_date": "2025-05-20",
    "status": "employee",
    "updated_at": "2025-05-06T18:11:15.676Z",
    "work_email": "[email protected]",
    "role": "employee",
    "company_id": "1",
    "created_by_type": "user",
    "created_by_user_id": "1",
    "external_identifier": null,
    "id": "6",
    "monthly_limit_reached": false,
    "personal_email": "[email protected]",
    "plan_type": "free",
    "salary_amount": 6198,
    "salary_currency": "USD",
    "supervisor": false,
    "supervisor_id": null
  }
}

Webhook Verification

Each event includes an X-Signature header containing a SHA256 HMAC hexdigest. This is generated using your API key and the body of the request.

Ruby Example

require 'openssl'

def verify_signature(api_key, payload, x_signature)
  expected_signature = OpenSSL::HMAC.hexdigest('SHA256', api_key, payload)
  expected_signature == x_signature
end

Processing Events

To properly process events:

Ensure yourtarget_url, listens for POST requests
Verify authenticity of event
Parse and process JSON payload
Respond with 200 OK