Managing webhook subscriptions

Webhook subscriptions are configured in the Unioo bank admin site, not through the External API. The External API is read/write for business data (organizations, reports, leads, etc.) — the webhook subscription that pushes that data to your systems is administrative and lives next to your API-key configuration in the admin UI.

See Webhooks for the conceptual overview, event catalog, and delivery semantics. See Receiving webhook deliveries for how to build the receiver itself.

Who can manage subscriptions

Only users on your bank that hold the HasDeveloperPrivileges role can see or modify webhook subscriptions. Users without the role will not see the Webhooks section on the API settings page at all. If you need access and the section is missing, ask one of your bank's user-management admins to grant the role.

Subscriptions are scoped to the bank you are signed in for. You can never see, modify, or delete a subscription belonging to a different bank.

Where the screen lives

Sign in to the Unioo bank admin site, then open Settings → API. The page is laid out as three stacked sections:

• API keys — outbound credentials for calling the External API. Not covered on this page.
• Webhooks — the subject of this page.
• Lead settings — only present for banks with the Leads module.

Click the + icon next to the Webhooks heading to open the New webhook overlay.

Create a subscription

The new-webhook overlay has three controls:

Control	Notes
Webhook URL	The HTTPS URL Unioo will POST deliveries to. The form validates that it parses as a URL.
Event-group checkboxes	One checkbox per group. Tick at least the groups you actually want deliveries for. The groups and their labels in the UI are listed in Event groups below.
Use Entra authentication	Toggle. When off, deliveries carry only the X-Unioo-Secret shared secret. When on, four extra fields appear — see Entra authentication.

Click Create webhook. Unioo immediately:

1. Stores the subscription. New subscriptions are active by default.
2. Generates the shared secret (a WH-… token).
3. Opens a Save the secret modal that displays the secret in full.

Save the secret before closing the modal

The secret is shown exactly once. The moment you dismiss the modal, the value is gone — there is no way to read it back from the UI later, and Unioo does not store it in a form anyone (including Unioo) can show you again. Capture it into your secrets manager (1Password, Vault, AWS Secrets Manager, etc.) before you click Ok.

If you lose it, use Regenerate the shared secret to mint a new value — there is no "show me the current one" option.

This is the value your receiver compares against the X-Unioo-Secret header on every delivery — see Receiving webhook deliveries for the verification rules.

Event groups

The checkboxes on the form map to the schema's event groups:

UI label	Schema name
Leads	LeadEvent
Invitations	InvitationEvent
Organizations	OrganizationEvent
Reports	BankReportEvent
Reports for review	BankReportReviewEvent
Bank requests	BankRequestEvent

The schema name is the one carried in delivery payloads — it's what your receiver routes on. See the event catalog for what each group fires on.

Subscribing to a group enrols you in every event type within it, current and future. If you only want a subset, filter on the type field in your receiver.

Entra authentication option

If you tick Use Entra authentication, four extra fields appear:

Field	Notes
Client ID	App registration client ID, must be a valid GUID.
Client Secret	The app's client secret. Stored encrypted at rest; only the last four characters are ever displayed back.
Tenant ID	Your Entra (Azure AD) tenant ID.
Token Scope	The scope Unioo will request a token for, e.g. api://your-receiver/.default.

All four are required to save when Entra is enabled. Unioo will mint a token through the confidential-client flow and send it as Authorization: Bearer <token> on every delivery to this subscription.

The shared X-Unioo-Secret header is still sent in Entra mode — you can validate either, both, or use the secret as a defence-in-depth check on top of JWT validation.

View existing subscriptions

The Webhooks section lists every subscription on your bank, each rendered as an inline row containing the URL, the Active toggle, the Use Entra authentication toggle, the event-group checkboxes, and (when Entra is configured) the Entra fields. The shared secret is never displayed in this list — it is only shown in the Save the secret modal on creation and regeneration.

Edit a subscription

Change any of the controls inline on the row — URL, active flag, event groups, Entra fields — and click Save on that row. Empty changes are detected: the Save button stays disabled until something differs from the stored value.

A few subtle rules worth knowing:

• Toggling Use Entra authentication off on an existing Entra-authenticated subscription and saving removes the stored credentials. The subscription falls back to shared-secret-only authentication.
• When Entra is already enabled, the Client Secret input shows a masked placeholder ending in the last four characters of the stored value. Leave the field blank to keep the existing secret; type a new value to rotate just the secret.
• The other Entra fields (Client ID, Tenant ID, Token Scope) behave the same way — leaving them unchanged means the stored value is untouched. Change one without retyping the others.

Pause a subscription without losing config

Flip the Active toggle on the row off and click Save. While inactive:

• Events for the subscription are still recorded on Unioo's side (with a WebhookInactive result).
• No HTTP request is made to your receiver.
• Toggle the flag back on and save to resume deliveries; no events that fired while paused are replayed.

This is the right thing to do when you're rolling out a receiver change and want to drain in-flight traffic without throwing away the configuration.

Regenerate the shared secret

If you have lost the secret, suspect it has leaked, or want to rotate it on a schedule, click Regenerate secret on the row.

1. A confirmation modal warns that the current secret stops working immediately.
2. Confirming generates a new WH-… value and re-opens the Save the secret modal with the new value on display.
3. Capture the new value before closing — same one-shot rules as on creation.

Rotation has no grace period — Unioo does not accept "old and new" simultaneously. Receivers still validating against the old secret will start rejecting deliveries (typically with HTTP 401) the moment you confirm. Plan the rollout:

1. Prepare your receiver to accept the new secret. The simplest pattern is to teach the receiver to compare against either an "old" and a "new" value during a brief rollover window.
2. Click Regenerate, capture the new value from the modal, and finish the cutover on the receiver.
3. Drop the old value once you've confirmed deliveries are landing.

Failed deliveries during a mismatch window are retried by Unioo's normal at-least-once retry loop, so transient 401s are replayed once the receiver knows the new value — you do not have to backfill manually.

Delete a subscription

Click Delete on the row and confirm in the modal. The subscription is removed; in-flight retries for it stop firing. Deletion is permanent — if you change your mind, create a fresh subscription and capture a new secret. The deleted subscription's secret is not reusable.

Common pitfalls

• "I don't see the Webhooks section on the API settings page." Your user is missing the HasDeveloperPrivileges role on the bank. Ask an admin to grant it.
• "My receiver rejects every delivery with 401." Either your receiver was never updated with the secret from the Save the secret modal, or you regenerated the secret and the receiver is still validating against the old one. There is no way to read the current secret out of the UI — regenerate to obtain a fresh, known value and roll it out.
• "I want to rotate the Client Secret without retyping the other Entra fields." Leave Client ID, Tenant ID, and Token Scope untouched; type the new value into Client Secret; click Save. Each Entra field is independently optional on an existing Entra-authenticated subscription.
• "I edited the URL and the Save button is greyed out." The form considers the row pristine until at least one control actually changed value. Click into the field again, or toggle another control, and Save will enable.