Overview

Webhooks provide real-time notifications when specific actions occur in the system.
Clients can register multiple webhook endpoints, each with a unique name and a custom set of subscribed actions.

A webhook is triggered only when one of its subscribed actions occurs.

Webhooks are event notifications, not data payloads. After receiving a webhook, clients must fetch the latest data using the appropriate APIs.

Webhook Subscription Model

Clients can create multiple webhooks

Each webhook must have:

A unique name

A public HTTPS endpoint

One or more actions

A single webhook can subscribe to multiple actions

Webhook Actions

Supported Actions

Action	Description
`task.created`	Triggered when a task is created.
`task.status.updated`	Triggered when the task status is updated.
`task.start_date.updated`	Triggered when the task start date is updated.
`task.end_date.updated`	Triggered when the task end date is updated.
`task.tags.updated`	Triggered when task tags are added, removed, or updated.
`task.category.updated`	Triggered when the task category is updated.
`task.requires_approval.updated`	Triggered when the task requires-approval flag is updated.
`task.approved`	Triggered when the task approved.
`task.checklist.updated`	Triggered when the task checklist or its attachments are created or updated.
`task.comment`	Triggered when a comment (with or without attachments) is created
`client.created`	Triggered when a client is created.
`equipment.created`	Triggered when equipment is created.
`venue.created`	Triggered when a venue is created.
`task_category.created`	Triggered when a task category is created.
`user.created`	Triggered when a user is created.
`tag.created`	Triggered when a tag is created.
`checklist_template.created`	Triggered when a checklist template is created.
`worklog.created`	Triggered when a worklog is created.
`worklog.updated`	Triggered when a worklog is updated.
`worklog.deleted`	Triggered when a worklog is deleted.
`task_material.created`	Triggered when task material is created.
`task_material.updated`	Triggered when task material is updated.
`task_material.deleted`	Triggered when task material is deleted.

1. Create Webhook

Endpoint

POST /webhooks

Description

Registers a new webhook with a unique name and a set of subscribed actions.

Request Body

{
  "name": "task-and-worklog-events",
  "url": "https://client-domain.com/webhooks/einpix",
  "actions": [
    "task.created",
    "task.updated",
    "worklog.created"
  ],
}

Validation Rules

name must be unique per client

url must be a public HTTPS endpoint and should allow POST data

actions must contain at least one valid action

Duplicate actions are not allowed

Success Response

{
  "id": 12,
  "name": "task-and-worklog-events",
  "url": "https://client-domain.com/webhooks/einpix",
  "actions": [
    "task.created",
    "task.updated",
    "worklog.created"
  ],
  "status": "active",
  "created": "2026-01-28T10:30:00Z"
}

2. Update Webhook

Endpoint

PUT /webhooks/{webhookId}

Description

Updates the webhook name, URL, or subscribed actions.

Request Body

{
  "name": "task-events-only",
  "actions": [
    "task.created",
    "task.updated",
    "task.deleted"
  ]
}

Success Response

{
  "id": 12,
  "status": "updated"
}

3. Delete Webhook

Endpoint

DELETE /webhooks/{webhookId}

Description

Deletes an existing webhook subscription.

Success Response

{
  "status": "deleted"
}

Webhook Event Delivery

Webhook Callback (Client Endpoint)

When a subscribed action occurs, a webhook request is sent to the registered URL.

Webhook Payload

Standard Payload Format

{
  "entity": "task | worklog | category",
  "id": 1
}

Field Description

Field	Type	Description
`entity`	string	Entity affected by the action.
`id`	integer	Unique identifier of the affected entity.

ℹ️ The action type is inferred from the webhook subscription and optional headers.

Webhook Headers

Content-Type: application/json
einpix-webhook-action: task.updated
einpix-webhook-name: task-and-worklog-events
einpix-webhook-signature: sha256=abc123...

Header	Description
`einpix-webhook-action`	Action that triggered the webhook.
`einpix-webhook-name`	Name of the webhook.
`einpix-webhook-signature`	HMAC signature used to verify the authenticity of the webhook request (Using api secret key).

Example Webhook Requests

Task Updated Event

POST /webhooks/einpix

{
  "action": "task.status.changed",
  "id": 101
}

Worklog Created Event

POST /webhooks/einpix

{
  "entity": "worklog.created",
  "id": 55
}

Task Checklist Updated

POST /webhooks/einpix

{
  "entity": "task.checklist.changed",
  "id": 55,
  "task_id": 1
}

Task Comment Created

POST /webhooks/einpix

{
  "entity": "task.comment.added",
  "id": 55,
  "task_id": 1
}

Expected Client Response

Clients must return a 2xx HTTP status code.

HTTP/1.1 200 OK

Non-2xx responses will trigger retries.

Error Handling & Retry Policy

Automatic retries on failure

Possible duplicate deliveries

Clients must implement idempotent processing

Security Best Practices

✔ HTTPS endpoints only

✔ Verify webhook signatures

✔ Log webhook deliveries

✔ Do not process unverified payloads

Troubleshooting

Webhook Not Triggered

Verify webhook is active

Ensure action is subscribed

Check endpoint accessibility

Signature Verification Failed

Ensure the correct secret is used

Validate the raw request body

Webhook

Overview#

Webhook Subscription Model#

Webhook Actions#

Supported Actions#

1. Create Webhook#

Endpoint#

Description#

Request Body#

Validation Rules#

Success Response#

2. Update Webhook#

Endpoint#

Description#

Request Body#

Success Response#

3. Delete Webhook#

Endpoint#

Description#

Success Response#

Webhook Event Delivery#

Webhook Callback (Client Endpoint)#

Webhook Payload#

Standard Payload Format#

Field Description#

Webhook Headers#

Example Webhook Requests#

Task Updated Event#

Worklog Created Event#

Task Checklist Updated#

Task Comment Created#

Expected Client Response#

Error Handling & Retry Policy#

Security Best Practices#

Troubleshooting#

Webhook Not Triggered#

Signature Verification Failed#

Overview

Webhook Subscription Model

Webhook Actions

Supported Actions

1. Create Webhook

Endpoint

Description

Request Body

Validation Rules

Success Response

2. Update Webhook

Endpoint

Description

Request Body

Success Response

3. Delete Webhook

Endpoint

Description

Success Response

Webhook Event Delivery

Webhook Callback (Client Endpoint)

Webhook Payload

Standard Payload Format

Field Description

Webhook Headers

Example Webhook Requests

Task Updated Event

Worklog Created Event

Task Checklist Updated

Task Comment Created

Expected Client Response

Error Handling & Retry Policy

Security Best Practices

Troubleshooting

Webhook Not Triggered

Signature Verification Failed