Webhooks

Umbra ERP uses webhooks to notify your server of events in real time. When a resource changes (e.g., invoice paid, lead created, employee added), Umbra ERP sends an HTTP POST request to your configured webhook URL. Webhook events fire on both Public API and internal UI operations.

Supported events

Resource	Events
Customer	`customer.created`, `customer.updated`, `customer.deleted`
Invoice	`invoice.created`, `invoice.updated`, `invoice.deleted`
Product	`product.created`, `product.updated`, `product.deleted`
Quote	`quote.created`, `quote.updated`, `quote.deleted`
Payment	`payment.created`
Employee	`employee.created`, `employee.updated`, `employee.deleted`
Leave	`leave.created`, `leave.updated`, `leave.deleted`
Loyalty	`loyalty.points_earned`, `loyalty.reward_redeemed`, `loyalty.tier_changed`, `loyalty.reminder_sent`

Payload format

Every webhook delivery wraps the resource data in an envelope:

{
  "event": "invoice.updated",
  "data": { /* full serialized resource */ },
  "timestamp": "2026-03-12T10:00:00Z",
  "deliveryId": "caf8e206-49bc-424c-b228-b4e4ac548f61"
}

Headers

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 hex digest of the payload
`X-Webhook-Event`	Event name (e.g. `invoice.updated`)
`X-Webhook-Delivery-Id`	Unique delivery UUID

Signature verification

Use your webhook secret (returned on creation) to verify the signature:

import hmac, hashlib

payload = request.body  # raw bytes
signature = request.headers["X-Webhook-Signature"]
expected = hmac.new(
    webhook_secret.encode(),
    payload,
    hashlib.sha256
).hexdigest()
assert hmac.compare_digest(signature, expected)

Maximum 10 webhooks per business. URLs must use HTTPS.

POST/v1/webhooks

Create webhook

Required attributes

Name
url
Type
string
Description
The HTTPS URL where Umbra ERP will send event notifications.
Name
events
Type
array
Description
List of event types to subscribe to (e.g., ["invoice.paid", "lead.created", "employee.added"]).

Request

POST

/v1/webhooks

curl -X POST https://api.umbraerp.com/v1/webhooks \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/umbra",
    "events": ["invoice.paid", "lead.created"]
  }'

Response

{
  "result": "success",
  "message": "Webhook created successfully."
}

GET/v1/webhooks

List webhooks

Retrieve all registered webhook URLs for your account.

Request

GET

/v1/webhooks

curl https://api.umbraerp.com/v1/webhooks \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "webhooks": [
    {
      "id": 1,
      "url": "https://yoursite.com/webhooks/umbra",
      "events": ["invoice.paid", "lead.created"],
      "is_active": true,
      "dateCreated": "2026-01-15T10:30:00Z"
    }
  ]
}

GET/v1/webhooks/:id

Fetch webhook

Retrieve details of a specific webhook by its ID.

Request

GET

/v1/webhooks/1

curl https://api.umbraerp.com/v1/webhooks/1 \
  -H "Authorization: Bearer <your_access_token>"

PUT/v1/webhooks/:id

Update webhook

Update an existing webhook URL or its subscribed events.

Optional attributes

Name
url
Type
string
Description
New HTTPS webhook URL.
Name
events
Type
array
Description
Updated list of event types.
Name
is_active
Type
boolean
Description
Enable or disable the webhook.

Request

PUT

/v1/webhooks/1

curl -X PUT https://api.umbraerp.com/v1/webhooks/1 \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yoursite.com/webhooks/umbra-v2",
    "is_active": true
  }'

Response

{
  "result": "success",
  "message": "Webhook updated successfully."
}

DELETE/v1/webhooks/:id

Delete webhook

Remove a webhook URL from your account.

Request

DELETE

/v1/webhooks/1

curl -X DELETE https://api.umbraerp.com/v1/webhooks/1 \
  -H "Authorization: Bearer <your_access_token>"

Response

{
  "result": "success",
  "message": "Webhook deleted successfully."
}