Custom webhooks

Send signed custom events to a ZenML webhook.

The custom webhook provider is a provider-neutral way to send signed JSON events to ZenML. Use it when a service can make HTTP requests but does not have a dedicated ZenML webhook provider.

Custom webhooks preserve the sender's event name and JSON payload for consumers. They do not define a ZenML semantic event catalog or provider-level payload filters. A custom webhook trigger uses an empty configuration and matches every accepted delivery for its webhook.

Create a custom webhook

Create the webhook and copy the generated signing secret:

zenml webhook create custom-events --type custom
zenml webhook describe custom-events

Via the SDK:

from zenml.client import Client
from zenml.webhooks.providers import BuiltinWebhookType

client = Client()
result = client.create_webhook(
    name="custom-events",
    webhook_type=BuiltinWebhookType.CUSTOM,
)

endpoint_url = result.endpoint_url
signing_secret = result.secret.get_secret_value()

See Create a webhook for lifecycle and secret-management options shared by all providers.

Delivery contract

Send an HTTP POST request whose body is a valid JSON object. The custom provider reads these headers:

Header	Required	Meaning
X-ZenML-Signature-256	Yes	sha256=<hex_digest> calculated with HMAC-SHA256 over the exact request body
X-ZenML-Event	Yes	The sender-defined event name made available to consumers
X-ZenML-Delivery	No	A sender-defined delivery identifier for observability

The payload must contain a JSON object at the top level. JSON arrays, scalar values, and malformed JSON return 400 Bad Request.

Send a signed event

Set the endpoint and secret captured during creation:

export WEBHOOK_URL="<endpoint-url-from-zenml>"
export WEBHOOK_SECRET="<signing-secret>"

Write the body, calculate its signature with Python, and send the same bytes with curl:

printf '%s' '{"model":"fraud-detector","version":"2026.08.31"}' > custom-event.json

export SIGNATURE="$(python -c 'import hashlib,hmac,os; body=open("custom-event.json","rb").read(); print("sha256=" + hmac.new(os.environ["WEBHOOK_SECRET"].encode(), body, hashlib.sha256).hexdigest())')"

curl -i -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-ZenML-Event: model.published" \
  -H "X-ZenML-Delivery: manual-delivery-001" \
  -H "X-ZenML-Signature-256: $SIGNATURE" \
  --data-binary @custom-event.json

A valid delivery returns 202 Accepted. The event name and parsed JSON object are then available to configured consumers. This response does not promise that a consumer matched or completed its work.

If authentication fails, verify that the sent body is byte-for-byte identical to the body used to calculate the signature. See Understand delivery responses for the shared response contract.

Related pages

• Webhooks
• Slack webhooks
• GitHub webhooks
• ClickUp webhooks
• Custom webhook triggers