Monitor onboarding

In this guide you’ll subscribe to your accounts’ events and unlock features when a capability is enabled. By the end onboarding finishes on its own and your application finds out about it. A capability is enabled by a reviewer on no 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 Setting up webhooks.
An API key with webhooks:write.

Steps

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.

curl -X POST https://sandbox-api.bachs.io/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Connect onboarding",
    "url": "https://example.com/webhooks/connect",
    "event_source": "connect",
    "event_types": ["account.updated", "capability.updated"]
  }'

{
  "endpoint_id": "whe_6a2f81c07b39d420f915",
  "name": "Connect onboarding",
  "url": "https://example.com/webhooks/connect",
  "enabled": true,
  "event_types": ["account.updated", "capability.updated"],
  "event_source": "connect",
  "signing_secret": "whsec_5f2a...",
  "created_at": "2026-08-07T09:20:00.000Z",
  "updated_at": "2026-08-07T09:20:00.000Z"
}

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.

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

{
  "type": "account.updated",
  "organization_id": "acct_3Wq8ZfT1yHnJ5sVe",
  "account": "acct_3Wq8ZfT1yHnJ5sVe",
  "data": {
    "account": "acct_3Wq8ZfT1yHnJ5sVe",
    "outstanding": ["persons.per_3a91c0d7.id_document"]
  }
}

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:

curl https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

{
  "id": "acct_3Wq8ZfT1yHnJ5sVe",
  "requirements": {
    "currently_due": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": ["persons.per_3a91c0d7.id_document"],
    "errors": [],
    "entries": [
      {
        "field": "persons.per_3a91c0d7.id_document",
        "status": "pending_verification",
        "restricts_capabilities": ["payouts"],
        "resolution": "review",
        "deadline": null,
        "errors": []
      }
    ],
    "current_deadline": null
  }
}

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:

Condition	What the screen shows
`requirements.errors` is not empty	”Fix these”, one row per error with its `reason`, which is written for the account holder to read. Each of these fields is also back in `currently_due`.
`past_due` or `currently_due` is not empty	”Provide these”, one input per field. Label each with `restricts_capabilities` so the account holder sees what it unlocks, and show `current_deadline` as a banner when it is set.
Everything is empty except `pending_verification`	”We are checking your details”, no inputs. There is nothing for the account holder to do.
`eventually_due` is not empty and nothing else is	”Nothing to do now”, optionally listing what will be asked for later.
Every bucket is empty	”Submitted”, not “you can start selling”. See the warning below.

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.

Unlock features from capability.updated

This is the event that says an account can do something.

capability.updated

{
  "type": "capability.updated",
  "organization_id": "acct_3Wq8ZfT1yHnJ5sVe",
  "account": "acct_3Wq8ZfT1yHnJ5sVe",
  "data": {
    "account": "acct_3Wq8ZfT1yHnJ5sVe",
    "capability": "payouts",
    "status": "active",
    "requested": true
  }
}

Gate on status == "active" for the specific capability you need. Every other value denies the action.

Reconcile after an outage

If your endpoint was down, read the current state rather than replaying assumptions:

curl https://sandbox-api.bachs.io/v1/accounts/acct_3Wq8ZfT1yHnJ5sVe/capabilities \
  -H "Authorization: Bearer sk_sandbox_abc123xyz..."

You can also re-deliver past events. See Replay 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 been enabled.

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.

Cause	Resolution
`event_types` is empty, or names an event type Bachs does not emit (400).	Send at least one valid type. `account.updated` and `capability.updated` are the two this guide needs.

Get started

Core concepts

Reversals and risk

Onboard an account

Build with Connect

Go live

Monitor onboarding

Before you start

Steps

What happens next

Errors

Next steps

​Before you start

​Steps

​What happens next

​Errors

​Next steps

Before you start

Steps

What happens next

Errors

Next steps