Skip to main content
In this guide you’ll subscribe to your accounts’ events and unlock features when a capability goes live. By the end onboarding finishes on its own and your application finds out about it. A capability goes live when its checks pass, and some wait for our team to review them. Neither happens on a fixed schedule, so polling is either too frequent to be useful or too slow to be timely. Subscribe instead. A recipient-only account holds fewer capabilities, so it fires fewer of these events over its life than one that also accepts payments. The events themselves work the same way regardless of which capabilities an account holds.

Before you start

  • A publicly reachable HTTPS endpoint. See Set up webhooks.
  • An API key with webhooks:write.

Steps

1

Create an endpoint that receives Connect events

Set event_source so the endpoint receives your accounts’ events. Without it, an endpoint receives only your own account’s events.
signing_secret is returned once, on creation. Store it to verify deliveries; it is not returned on a later read of the endpoint. Use all on a single endpoint if you would rather handle your own events and your accounts’ events in one place.
2

Know when an account has new things to do

When you ask for a capability, the account may owe more. account.tasks_requested tells you the moment we make new tasks for it, with their ids in data.task_ids. Send the person their onboarding link then. See account.tasks_requested.
3

Show progress from account.updated

The event tells you the account’s requirement state changed, and data.outstanding lists the field keys still being asked for. That list alone answers “is there anything left for this account to do”.
account.updated
Read the account id from account, or from organization_id when account is absent. On a Connect event organization_id is the account, not your platform.The event carries only the keys. To label them, say which are your problem, and say which are waiting on us, read the account and use its requirements block:
Each entry’s resolution is the one that decides what your screen offers: api means the value is yours to send, so show an input. review means it is already with us, so show a wait state and no input, because re-sending it changes nothing.That gives you the screen states below. Check them in this order and show the first one that matches:Re-read the account on every account.updated rather than tracking state yourself. Requirements are recomputed on each read, so the account is the truth and the event is the trigger.
4

Unlock features from capability.updated

This is the event that says an account can do something.
capability.updated
Gate on status == "active" for the specific capability you need. Every other value denies the action.
5

Reconcile after an outage

If your endpoint was down, read the current state rather than replaying assumptions:
You can also re-deliver past events. See Replay webhook events.
An empty outstanding, or an account whose requirement buckets are all empty, means nothing is outstanding, not that a capability is on. Unlocking features on account.updated will let an account act before it has gone live.

What happens next

A capability can change more than once over an account’s life, including back to restricted. Handle capability.updated as a state change every time rather than a one-off unlock, and re-check before actions that move money.

Errors

Endpoint creation returns the standard error envelope.

Next steps