Managing endpoints

The nine webhook routes, the permission each needs, and how to rotate a signing secret safely.

Choose a credential

CredentialHeaderLastsUse it for
API keyx-api-key: <key>Up to a year, until revokedAnything automated. It names one organisation and can only manage webhooks.
Access tokenAuthorization: Bearer <token>12 hoursA 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 }'
labelstringrequired

What this key is for, so you can tell your keys apart later.

expiresInDaysintegerdefault: 365

How long the key lasts, between 1 and 365 days.

keystring

The API key, returned here only. Only a hash of it is stored, so a lost key cannot be recovered: issue another one.

uuidstring
The key's id, used to revoke it.
keyPrefixstring

The start of the key. It is not secret, and it is how the list tells you which key is which.

expiresAtstring
When the key stops working.

Then 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.

OperationRoutePermission
List this organisation's keysGET /v3/webhook-keys4806
Issue a keyPOST /v3/webhook-keys4801 to 4806
Revoke a keyPOST /v3/webhook-keys/{uuid}/revoke4806

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.

StatusMeaning
401On 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.
403The key does not hold the permission that route needs.
404Revoking: no such key in your organisation.
409Issuing: the organisation already holds two live keys.
429The 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.

StatusMeaning
400The sign-in was refused: wrong email or password, or the request is missing one.
401On a webhook route: no credential, or the token is expired or ended by a property switch. A partner OAuth token is also refused here.
403The 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.

OperationRoutePermission
List this organisation's endpointsGET /v3/webhooks4801 · WebhooksView
Read the subscribable eventsGET /v3/webhooks/events4801 · WebhooksView
Read one endpointGET /v3/webhooks/{uuid}4801 · WebhooksView
Read an endpoint's delivery logGET /v3/webhooks/{uuid}/executions4801 · WebhooksView
Register an endpointPOST /v3/webhooks4802 · WebhooksCreate
Change, enable or disable an endpointPATCH /v3/webhooks/{uuid}4803 · WebhooksEdit
Fire a test eventPOST /v3/webhooks/{uuid}/test4803 · WebhooksEdit
Rotate the signing secretPOST /v3/webhooks/{uuid}/rotate-secret4805 · WebhooksRotateSecret
Delete an endpointDELETE /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

namestringrequired

Operator-facing name, 1–200 characters.

urlstringrequired

The HTTPS endpoint, at most 500 characters. See URL requirements.

eventTypesstring[]required

Between 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.

descriptionstring

What this endpoint is for, at most 500 characters.

branchIdinteger

Narrow 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-Keyheaderrequired

A 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:

signingSecretstring

A 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.

subscriptionsnumber

How many event subscriptions were created — one per unique event name.

replayedboolean

false here. See Retrying a registration.

StatusMeaning
200This Idempotency-Key already registered this endpoint. Nothing new was created, and signingSecret is null. See Retrying a registration.
400The 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.
403Your session does not name a single organisation. Webhooks belong to one organisation.
409This 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.
428The Idempotency-Key header is missing. Nothing was created.
503The 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:

replayedboolean
true.
signingSecretnull

Always null here. The secret is shown once, and this call does not change it.

rotateSecretPathstring

The 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

uuidstring
The endpoint's id. Use this on every other route.
namestring
descriptionstring | null
urlstring
eventTypesstring[]
What this endpoint is subscribed to.
enabledboolean
When false, deliveries are skipped rather than failed.
branchIdnumber | null
lastTriggeredAtstring | null
The last time a delivery was attempted.
lastSuccessAtstring | null
The last 2xx. Still null means nothing has ever got through.
lastFailureAtstring | null
totalAttemptsnumber
totalSuccessesnumber
totalFailuresnumber
createdAtstring | null

The 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: 50

How 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

namestring
1–200 characters.
descriptionstring
At most 500 characters.
urlstring
Re-validated against the URL requirements.
enabledboolean
false pauses the endpoint without deleting it.

Fire a test event

POST /v3/webhooks/{uuid}/test · permission 4803

eventTypestringdefault: cash.payment.received

Which event to send a synthetic instance of.

deliveredboolean
Whether your endpoint answered 2xx.
statusCodenumber | null
The status your endpoint returned, or null if nothing answered.
durationMsnumber
How long the attempt took.
errorstring | null
Why it failed, when it failed.

It 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:

  1. 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.

  2. Rotate and capture the new secret

    Call rotate-secret. The response is the only place the new value appears — store it immediately.

  3. 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.

  4. 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.

StatusMeaning
404No such endpoint in your organisation.
503The 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.