Webhooks

Webhooks is the escape hatch for everything without a tile of its own. It does two separate jobs: inbound, it mints signed addresses any external tool can POST JSON to, which start a Webhook received automation; outbound, it holds the key your automations sign their deliveries with. No provider account is involved in either direction.

Create an inbound endpoint

Address-only or signed

	Address only	Signed
What proves the call	The URL itself is the secret	The URL, plus an HMAC signature on every request
Good for	A tool that only lets you paste a URL	Anything that can sign, and anything that matters
What you copy	The address	The address and the signing secret

Mapping fields onto a lead

The six mapping fields take dot paths into the body the sender posts. If your sender posts this:

{ "contact": { "email": "dana@example.com", "full_name": "Dana Reyes" } }

then the email path is contact.email and the name path is contact.full_name.

With an email mapped, the endpoint lands a lead — or reuses an existing one with that email. Without an email, no lead is created and the automation still runs on the payload. Mapping is optional: an endpoint that only starts an automation needs no mapping at all.

The signature scheme

One scheme works in both directions, so any third party can speak it either way.

X-Zyan-Timestamp: <unix seconds or milliseconds>
X-Zyan-Signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>">

The signed string is the timestamp, a full stop, then the raw request body — the exact bytes, before any parsing. Timestamps are accepted within five minutes either side.

Direction	Which secret	Who needs it
Inbound	The endpoint's inbound signing secret	Whoever sends you webhooks, so they can sign
Outbound	Your outbound signing key	Whoever receives your deliveries, so they can verify

Sending webhooks out

Add a Send webhook step to an automation. It POSTs or PUTs a signed JSON envelope to any public https URL you type. Map the fields you want under data, and add up to five extra headers if the receiver needs them.

The envelope shape:

{
  "event": "lead.created",
  "data": { "email": "dana@example.com" },
  "sent_at": "2026-01-01T12:00:00.000Z",
  "source": "zyan"
}

Deliveries also carry X-Zyan-Event, X-Zyan-Event-Id and a Zyan-Webhooks/1 user agent, alongside the timestamp and signature headers.

Rotate, disable, delete

Action	What it does
Rotate	Replaces the address token only. The old address stops working immediately, and the new one is shown once
Disable	Acknowledges senders with a 200 and writes nothing
Delete	Removes the endpoint entirely

Limits

Limit	Value
Request body	128 KB
Payload nesting depth	4
Keys per object	200
Array length	50
String length	2,000
Receipts per endpoint	1,000 per hour
Receipts per workspace	2,000 per hour
New leads per workspace	100 per hour

Troubleshooting

Symptom	Cause	Fix
The sender gets a 401 or 404	The token is wrong, or the address was rotated	Re-copy the address from the Webhooks tile and paste it into the sender
You cannot tell whether the endpoint or the token is wrong	An unknown endpoint and a wrong token look identical from outside, deliberately	Re-copy the whole address rather than guessing
Your signature never verifies	The signed string is the timestamp, a full stop, then the raw body	Sign the raw bytes, not a re-serialised object
Requests are rejected as stale	Timestamps are accepted within five minutes either side	Check the sending server's clock
No lead is created	No email path is mapped, or the payload has no email at that path	Map email to the right dot path
A big payload is rejected	The body is over 128 KB, or the structure is too deep or too wide	Send a smaller payload
Deliveries stop after a burst	The per-endpoint or per-workspace hourly cap was reached	Spread the sends out
You lost the address or the secret	Both are shown exactly once	Rotate to mint a new address; for a new secret, switch to address-only and back

Related

• Build your first automation
• Triggers and steps reference
• Integrations directory
• Post leads from your own form