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
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.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#
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#
Webhook Event Delivery#
Webhook Callback (Client Endpoint)#
When a subscribed action occurs, a webhook request is sent to the registered URL.Webhook Payload#
{
"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.Content-Type: application/json
X-Webhook-Action: task.updated
X-Webhook-Name: task-and-worklog-events
X-Webhook-Signature: sha256=abc123...
| Header | Description |
|---|
X-Webhook-Action | Action that triggered the webhook. |
X-Webhook-Name | Name of the webhook. |
X-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
}
POST /webhooks/einpix
{
"entity": "task.comment.added",
"id": 55,
"task_id": 1
}
Expected Client Response#
Clients must return a 2xx HTTP status code.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#
✔ Verify webhook signatures
✔ Do not process unverified payloads
Troubleshooting#
Webhook Not Triggered#
Ensure action is subscribed
Check endpoint accessibility
Signature Verification Failed#
Ensure the correct secret is used
Validate the raw request body
Modified at 2026-02-02 06:23:56
