Webhooks

Webhooks push events to your systems in real time, so you don't have to poll the API. Register a URL, pick the events you care about, and Knowledge ERP will POST to it when they occur.

Registering a webhook #

Create a webhook with:

• a name to identify it,
• a URL to receive the callbacks,
• a list of events to subscribe to,
• an active flag to pause/resume it.

The system generates a random secret for you on creation. It is returned once — in the response to the create request (and shown once in the UI) — and never again on subsequent list, show, or update calls, so store it securely. It is used to verify the signature of incoming payloads.

Available events #

Events follow a resource.action naming scheme, including:

• customer.created / .updated / .deleted
• inventory.item.created / .updated / .deleted / .checked_out / .checked_in
• inventory.movement.created
• sales_order.created / .updated / .deleted
• purchase_order.created / .updated / .received
• customer_invoice.created / .paid, vendor_invoice.created / .paid
• work_order.created / .updated / .status_changed
• opportunity.created / .won / .lost / .stage_changed
• appointment.created / .updated / .deleted
• rental.reserved / .picked_up / .returned / .closed / .cancelled
• survey.completed / .low_score
• questionnaire.completed

To subscribe to every event with a single webhook, use the * wildcard as the only entry in the events list.

Verifying the signature #

Every delivery is signed. Knowledge ERP computes an HMAC-SHA256 of the request body using your webhook's secret and sends it as a header, alongside the event name:

X-Webhook-Signature: sha256=<hmac>
X-Webhook-Event: sales_order.created

Recompute the HMAC on your end with the same secret and compare — reject the request if it doesn't match.

Delivery log #

Each attempt is recorded in a delivery log (event, response, status), so you can confirm what was sent and diagnose failures without guessing.

Doing it from the API #

# List your webhooks
curl "https://your-domain.com/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN"

# Create a webhook — the response includes the signing secret this one time
curl -X POST "https://your-domain.com/api/v1/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order notifications",
    "url": "https://example.com/hooks/knowledge-erp",
    "events": ["sales_order.created", "customer_invoice.paid"]
  }'

The secret field is only present in this create response. Capture it now — it is never returned again. Use "events": ["*"] to receive every event.