Choose a credential
| Credential | Header | Lasts | Use it for |
|---|---|---|---|
| API key | x-api-key: <key> | Up to a year, until revoked | Anything automated. It names one organisation and can only manage webhooks. |
| Access token | Authorization: Bearer <token> | 12 hours | A person setting up by hand, and issuing or revoking API keys by API. |
Send one or the other. A request carrying both answers 401.
Your receiver needs neither. It verifies deliveries with the signing secret, and an endpoint keeps receiving deliveries after the credential that registered it has expired or been revoked.
Use an API key
An Admin or Account Owner issues a key in the app or by API.
In the app: go to Settings > Integrations > Webhook API keys and choose Issue a key. You see the key once, when you issue it, so copy it to your secret store before you close the dialog.
By API: use an access token:
curl -s -X POST https://api.nyumbazetu.com/v3/webhook-keys \
-H "Authorization: Bearer $NZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "label": "Payments integration", "expiresInDays": 365 }'
labelstringrequiredWhat this key is for, so you can tell your keys apart later.
expiresInDaysintegerdefault: 365How long the key lasts, between 1 and 365 days.
keystringThe API key, returned here only. Only a hash of it is stored, so a lost key cannot be recovered: issue another one.
uuidstringkeyPrefixstringThe start of the key. It is not secret, and it is how the list tells you which key is which.
expiresAtstringThen send it on any /v3/webhooks route:
curl -s https://api.nyumbazetu.com/v3/webhooks \
-H "x-api-key: $NZ_API_KEY"
It names one organisation. That is the organisation of the person who issued it, and no request can point it at another. Check you are signed in to the right organisation before you issue one.
It holds only the webhook permissions 4801 to 4805. It cannot read anything
else in NyumbaZetu, and it cannot issue or revoke keys.
It belongs to the organisation, not to a person. It keeps working when the person who issued it leaves or switches property. Endpoints it registers record no person as their creator.
It allows 120 requests a minute. Beyond that it answers 429, with
details.retryAfterSeconds saying how long to wait.
Who can issue a key
Issuing, listing and revoking need permission 4806 · WebhookKeysManage, which
Admin and Account Owner hold. Issuing also needs 4801 to 4805, because nobody can
issue a key with permissions they do not hold themselves. An API key can never do any
of this, so a leaked key cannot create another one.
| Operation | Route | Permission |
|---|---|---|
| List this organisation's keys | GET /v3/webhook-keys | 4806 |
| Issue a key | POST /v3/webhook-keys | 4801 to 4806 |
| Revoke a key | POST /v3/webhook-keys/{uuid}/revoke | 4806 |
The list never includes a key's secret. It does show lastUsedAt, expiresAt and
whether each key is active.
Revoke or rotate a key
In the app, choose Revoke beside the key on the Webhook API keys page. By API:
curl -s -X POST https://api.nyumbazetu.com/v3/webhook-keys/{uuid}/revoke \
-H "Authorization: Bearer $NZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "reason": "Rotated" }'
A revoked key answers 401 on its next call. Revoking cannot be undone.
An organisation can hold two live keys at once, so you can rotate without a gap: issue
a second key, move your integration to it, check lastUsedAt to confirm the old key
has gone quiet, then revoke the old one. A third key is refused with 409 until one
is revoked or expires. Nothing warns you before a key expires, so note expiresAt and
rotate ahead of it.
| Status | Meaning |
|---|---|
401 | On a webhook route: the key is unknown, wrong, expired or revoked, or its organisation has closed. These all answer the same way. On a /v3/webhook-keys route: no access token, because those routes refuse an API key. |
403 | The key does not hold the permission that route needs. |
404 | Revoking: no such key in your organisation. |
409 | Issuing: the organisation already holds two live keys. |
429 | The key is over its limit. |
Get an access token
The bearer token comes from signing in with a NyumbaZetu user:
curl -s -X POST https://api.nyumbazetu.com/v1/auth/authenticate \
-H "Content-Type: application/json" \
-d '{ "email": "you@example.com", "password": "your-password" }'
Send accessToken from the response as Authorization: Bearer <token>. The
response also has a user object, whose orgId is the organisation the token acts
on.
The user's role must hold the permission. Admin and Account Owner hold all five
webhook permissions. Any other role gets 403 unless it has been granted them.
It lasts 12 hours. To renew it before then, send it to
POST /v1/auth/sign-in-with-token as { "accessToken": "…" }. After it expires,
sign in again.
Its organisation follows the property the user is on. If the user works in more
than one organisation, check user.orgId before you register anything. If it is the
wrong one, switch to a property in the right organisation in the app and sign in again.
Switching property ends it. If the same user switches property in the app, the
token answers 401 until you sign in again. For anything automated, use an
API key instead.
| Status | Meaning |
|---|---|
400 | The sign-in was refused: wrong email or password, or the request is missing one. |
401 | On a webhook route: no credential, or the token is expired or ended by a property switch. A partner OAuth token is also refused here. |
403 | The token's user does not hold the permission that route needs. |
Routes and permissions
Each route requires a specific permission on the calling role. An API key holds all five.
| Operation | Route | Permission |
|---|---|---|
| List this organisation's endpoints | GET /v3/webhooks | 4801 · WebhooksView |
| Read the subscribable events | GET /v3/webhooks/events | 4801 · WebhooksView |
| Read one endpoint | GET /v3/webhooks/{uuid} | 4801 · WebhooksView |
| Read an endpoint's delivery log | GET /v3/webhooks/{uuid}/executions | 4801 · WebhooksView |
| Register an endpoint | POST /v3/webhooks | 4802 · WebhooksCreate |
| Change, enable or disable an endpoint | PATCH /v3/webhooks/{uuid} | 4803 · WebhooksEdit |
| Fire a test event | POST /v3/webhooks/{uuid}/test | 4803 · WebhooksEdit |
| Rotate the signing secret | POST /v3/webhooks/{uuid}/rotate-secret | 4805 · WebhooksRotateSecret |
| Delete an endpoint | DELETE /v3/webhooks/{uuid} | 4804 · WebhooksDelete |
Rotation is its own permission, separate from edit, because it breaks a working integration until the subscriber redeploys — and because an operator may reasonably hold one without the other.
Register an endpoint
POST /v3/webhooks · permission 4802
namestringrequiredOperator-facing name, 1–200 characters.
urlstringrequiredThe HTTPS endpoint, at most 500 characters. See URL requirements.
eventTypesstring[]requiredBetween 1 and 50 event names from the subscribable list. Duplicates are collapsed. An unknown or non-public name is refused here, rather than accepted and then never delivered.
descriptionstringWhat this endpoint is for, at most 500 characters.
branchIdintegerNarrow this endpoint to a single branch of your organisation. Omit for organisation-wide. A branch of another organisation is refused.
A narrowed endpoint receives only that branch's events. An
organisation-wide event — one whose data.branch_id is null — never reaches
it, and neither does another branch's. To receive organisation-wide events,
register an endpoint without branchId; it receives every branch's events as
well.
Idempotency-KeyheaderrequiredA value you choose for this one registration, at most 255 characters. A UUID works well. Send the same value if you retry. See Retrying a registration.
curl -s -X POST https://api.nyumbazetu.com/v3/webhooks \
-H "Authorization: Bearer $NZ_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1d2c9e-4a7b-4e15-9b0a-2f8c3d7e1a55" \
-d '{
"name": "Ops notifier",
"url": "https://hooks.example.com/nyumbazetu",
"eventTypes": ["cash.payment.received"],
"branchId": 2187
}'
The 201 response is the endpoint as read back, plus:
signingSecretstringA 64-character hex secret, returned here and from rotate-secret only. No
read route returns it, no delivery log stores it, and it is encrypted at rest.
subscriptionsnumberHow many event subscriptions were created — one per unique event name.
replayedbooleanfalse here. See Retrying a registration.
| Status | Meaning |
|---|---|
200 | This Idempotency-Key already registered this endpoint. Nothing new was created, and signingSecret is null. See Retrying a registration. |
400 | The URL is not an acceptable endpoint, an event name is not available for webhook subscription, branchId is not a branch of your organisation, or the Idempotency-Key is empty or longer than 255 characters. |
403 | Your session does not name a single organisation. Webhooks belong to one organisation. |
409 | This Idempotency-Key was already used. code is IDEMPOTENCY_KEY_REUSED when it was for a different request, or BUSINESS_WEBHOOK_CREATE_KEY_ENDPOINT_DELETED when the endpoint it registered has since been deleted. Use a new key. |
428 | The Idempotency-Key header is missing. Nothing was created. |
503 | The credential store has no encryption key, so no signing secret can be stored safely. Nothing was created. |
A refused registration leaves nothing behind: the endpoint, its subscriptions and its secret are created as one unit, or not at all. It does not use up the key either, so you can fix the request and send it again with the same key.
Retrying a registration
If you lost the response to a timeout, send the same request again with the same
Idempotency-Key. You get one endpoint however many times you send it. Keys belong
to your organisation, so another organisation using the same value has no effect on
yours.
If the endpoint was already created, the answer is 200 with an
Idempotency-Replayed: true header, and the endpoint as first registered, with:
replayedbooleantrue.signingSecretnullAlways null here. The secret is shown once, and this call does not change it.
rotateSecretPathstringThe route that gets you a new secret: /v3/webhooks/{uuid}/rotate-secret.
URL requirements
https only. http is refused, and so is any other scheme.
No credentials in the URL. A user:password@host form is refused.
Must resolve to a public address. Refused if the hostname is in a
private-by-name namespace, or if any address it resolves to is private,
loopback, link-local or otherwise reserved — including 169.254.169.254. A host
that answers with one public and one private address is refused outright.
Must resolve at all. A hostname that does not resolve, or resolves to no addresses, is refused at send time.
These checks run at registration, again when you change the URL, and again on every delivery — because a hostname that is public today can point inward tomorrow. The address that passes the check is the one the request is pinned to, so the name cannot be re-resolved to something else between the check and the connection.
Read an endpoint
GET /v3/webhooks/{uuid} · permission 4801
uuidstringnamestringdescriptionstring | nullurlstringeventTypesstring[]enabledbooleanfalse, deliveries are skipped rather than failed.branchIdnumber | nulllastTriggeredAtstring | nulllastSuccessAtstring | null2xx. Still null means nothing has ever got through.lastFailureAtstring | nulltotalAttemptsnumbertotalSuccessesnumbertotalFailuresnumbercreatedAtstring | nullThe signing secret is not in this response, and there is no field that holds
it. GET /v3/webhooks returns the same shape as an array.
Read the delivery log
GET /v3/webhooks/{uuid}/executions · permission 4801
limitintegerdefault: 50How many of the most recent attempts to return, clamped to between 1 and 200.
Rows are newest first and carry the event type, the URL and method used, the response status, the delivery status, the duration in milliseconds, any error message, and the request and response headers.
Change, enable or disable an endpoint
PATCH /v3/webhooks/{uuid} · permission 4803
namestringdescriptionstringurlstringenabledbooleanfalse pauses the endpoint without deleting it.Fire a test event
POST /v3/webhooks/{uuid}/test · permission 4803
eventTypestringdefault: cash.payment.receivedWhich event to send a synthetic instance of.
deliveredboolean2xx.statusCodenumber | nullnull if nothing answered.durationMsnumbererrorstring | nullIt goes through the real delivery path — same signing, same address checks, same delivery log — so a pass here means a real delivery will pass. It is a single attempt: not queued, not retried.
The synthetic body uses the same envelope as a real delivery but its data is
marked test: true and carries no entity reference. It proves transport and
signature verification, not your payload handling. See
the envelope.
Rotating the signing secret
POST /v3/webhooks/{uuid}/rotate-secret · permission 4805
curl -s -X POST \
https://api.nyumbazetu.com/v3/webhooks/{uuid}/rotate-secret \
-H "Authorization: Bearer $NZ_TOKEN"
{
"success": true,
"data": {
"uuid": "9f1c7e5a-3b2d-4f80-8c11-6a2d9e4b7c03",
"signingSecret": "…a new 64-character hex secret…"
},
"message": "Rotated. Deploy this secret to your endpoint — the previous one no longer verifies."
}
How to rotate without dropping deliveries
The overlap has to live on your side. Accept two secrets for the duration:
Teach your endpoint to accept two secrets
Read a primary and an optional secondary secret from your configuration. Compute the expected signature for each and constant-time compare against both; accept if either matches. Deploy this before you rotate.
Rotate and capture the new secret
Call
rotate-secret. The response is the only place the new value appears — store it immediately.Promote the new secret, keep the old one as secondary
Set primary to the new secret and secondary to the old one, and deploy. From this moment anything already in flight, signed with either, still verifies.
Drop the old secret
Once more than the 300-second replay window has passed — in practice, once you have seen successful deliveries and the delivery log is clean — remove the secondary and deploy again.
Rotate when you believe the secret has been exposed, when someone with access to it leaves, or on whatever schedule your own policy sets. A lost secret can only be replaced by rotating — there is no recovery, because the platform never stores a readable copy.
Retrying a rotation
If you lost the response to a timeout, call rotate-secret again. Each call sets a
new secret and answers with it, so the secret in the last response you received is
the live one. This route ignores Idempotency-Key, because a repeat could not show
you the secret again.
Wait for one call to answer or time out before you send the next. If two run at the same time, the response you keep may not hold the live secret. Signatures then fail to verify, and rotating once more fixes it.
| Status | Meaning |
|---|---|
404 | No such endpoint in your organisation. |
503 | The credential store has no encryption key. The old secret is unchanged. |
Delete an endpoint
DELETE /v3/webhooks/{uuid} · permission 4804
Deliveries stop. Any delivery still queued for the endpoint fails permanently rather than being retried, because the endpoint it names no longer exists.
Deleting is not reversible by re-registering: a new registration is a new endpoint, with a new uuid and a new secret, and it receives nothing that happened before it was created.