Webhook alerts

1. Concepts

What a webhook alert does

A webhook alert sends an HTTP POST request to an endpoint whenever a subscribed event happens in Zenskar, for example when a customer is created or an invoice is approved.

Event categories and Contracts V3

Webhook events are organized into five categories: Customer, Invoice, Contract, Payment, and Entitlement. Organizations on Contracts V3 can only subscribe to Customer and Payment events. Invoice, Contract, and Entitlement events are not selectable when creating or editing a webhook under Contracts V3.

The event picker in the webhook form does not currently expose every event Zenskar can send. invoice.cancelled and entitlement.expired exist but are not selectable when creating or editing a webhook.

Enabling and disabling a webhook

A webhook can be paused without deleting it, keeping its configuration in place while stopping deliveries until it is resumed.

Verifying a delivery

Each webhook delivery includes a signature, so the receiving system can confirm it came from Zenskar and was not altered in transit. Validate this signature before acting on a payload.

2. How-to guides

Create a webhook

Click the account menu at the bottom of the sidebar, and select Settings.
Open the Webhook Alerts tab.
Click Add Webhook Alert.
Enter a Webhook Name.
Optionally click Add Description to add a description.
Enter the Endpoint URL that should receive the payload.
Enter a Secret Key. Use a long, random value.
Leave Enable Webhook Alerts checked to activate the webhook immediately, or uncheck it to create it disabled.
Select the events to subscribe to.
Click Create.

Edit a webhook

Open Settings > Webhook Alerts.
Open the actions menu on the webhook’s row, and select Edit.
Update any of the fields described in Create a webhook.
Click Update.

Pause or resume a webhook

Open the actions menu on the webhook’s row, and select Pause or Resume.

Delete a webhook

Open Settings > Webhook Alerts.
Open the actions menu on the webhook’s row, and select Delete.
Confirm the deletion.

View a webhook’s delivery history

Open Settings > Webhook Alerts, and click a webhook’s row.
The Alerts History panel lists past deliveries.
Select a delivery to see its Triggered Webhook Details (webhook ID, status, and when it was last updated) and its Event Information (the JSON payload sent).

Resend a delivery

Open a delivery’s details, and use Resend to trigger it again.

Validate a webhook signature

Compute an HMAC using SHA256 with the secret key over the raw payload body, and compare it against the value in the X-Signature header, which is prefixed with sha256=.

def verify_signature(payload_body, secret_token, signature_header):
    """Verify that the payload was sent from Zenskar by validating SHA256.

    Raise and return 403 if not authorized.

    Args:
        payload_body: original request body to verify (request.body())
        secret_token: Zenskar webhook token (WEBHOOK_SECRET)
        signature_header: header received from Zenskar (X-Signature)
    """
    if not signature_header:
        raise HTTPException(status_code=403, detail="X-Signature header is missing!")
    hash_object = hmac.new(secret_token.encode('utf-8'), msg=payload_body, digestmod=hashlib.sha256)
    expected_signature = "sha256=" + hash_object.hexdigest()
    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=403, detail="Request signatures didn't match!")

Troubleshooting

Contract, invoice, or entitlement events are not selectable: these categories are not available in the webhook form for organizations on Contracts V3.
A delivery shows Failed: the endpoint did not return an HTTP 200 response. Confirm the endpoint is reachable and returns 200 on success.
The signature does not match: recompute the hash using the exact raw request body, not a re-serialized version of it. Re-serializing JSON can change the byte-for-byte content and produce a different hash.

3. Reference

Location

Settings > Webhook Alerts.

Fields

Field	Required	Notes
Webhook Name	Yes
Description	No	Hidden behind an Add Description action until used
Endpoint URL	Yes	Receives the payload through an HTTP POST request
Secret Key	Yes	Used to sign each payload
Enable Webhook Alerts	No	Checked by default
Events	No	Which events this webhook subscribes to

Event catalog

Category	Event	Description
Customer	`customer.created`	A new customer is created
Customer	`customer.updated`	Customer metadata, phases, or pricing is modified
Invoice	`invoice.created`	A new invoice is created
Invoice	`invoice.updated`	An invoice status is modified
Invoice	`invoice.deleted`	A draft invoice is deleted
Invoice	`invoice.approved`	An invoice is approved
Invoice	`invoice.voided`	An invoice is voided
Invoice	`invoice.cancelled`	An invoice is cancelled
Invoice	`invoice.regenerated`	An invoice is regenerated
Contract	`contract.created`	A new contract is created
Contract	`contract.updated`	Contract metadata, phases, or pricing is modified
Contract	`contract.activated`	Contract status changes to active
Contract	`contract.deleted`	A contract is deleted
Payment	`payment.created`	A payment is created
Payment	`payment.updated`	A payment is updated
Payment	`payment.succeeded`	A payment succeeds
Payment	`payment.failed`	A payment fails
Payment	`payment.refunded`	A payment is refunded
Entitlement	`entitlement.granted`	An entitlement is granted
Entitlement	`entitlement.exhausted`	An entitlement is exhausted
Entitlement	`entitlement.expired`	An entitlement expires

Event availability by contract experience

Category	Earlier experience	Contracts V3
Customer	Available	Available
Payment	Available	Available
Invoice	Available	Not selectable in the webhook form
Contract	Available	Not selectable in the webhook form
Entitlement	Available	Not selectable in the webhook form

Delivery status

Status	Meaning
Succeeded	The endpoint returned an HTTP 200 response
Failed	The endpoint did not return an HTTP 200 response

Signature validation

Detail	Value
Header	`X-Signature`
Algorithm	HMAC using SHA256
Format	Prefixed with `sha256=`

Getting started

Product modules

Security

Model context protocol (MCP)

Pricing models

Third-party integrations

Zenskar versioning

1. Concepts

What a webhook alert does

Event categories and Contracts V3

Enabling and disabling a webhook

Verifying a delivery

2. How-to guides

Create a webhook

Edit a webhook

Pause or resume a webhook

Delete a webhook

View a webhook’s delivery history

Resend a delivery

Validate a webhook signature

Troubleshooting

3. Reference

Location

Fields

Event catalog

Event availability by contract experience

Delivery status

Signature validation

​1. Concepts

​What a webhook alert does

​Event categories and Contracts V3

​Enabling and disabling a webhook

​Verifying a delivery

​2. How-to guides

​Create a webhook

​Edit a webhook

​Pause or resume a webhook

​Delete a webhook

​View a webhook’s delivery history

​Resend a delivery

​Validate a webhook signature

​Troubleshooting

​3. Reference

​Location

​Fields

​Event catalog

​Event availability by contract experience

​Delivery status

​Signature validation

1. Concepts

What a webhook alert does

Event categories and Contracts V3

Enabling and disabling a webhook

Verifying a delivery

2. How-to guides

Create a webhook

Edit a webhook

Pause or resume a webhook

Delete a webhook

View a webhook’s delivery history

Resend a delivery

Validate a webhook signature

Troubleshooting

3. Reference

Location

Fields

Event catalog

Event availability by contract experience

Delivery status

Signature validation