Webhooks

Webhooks notify your platform when connected account state changes.

They allow your system to react to verification updates, requirement changes, and capability transitions.

Why use webhooks

Some account state changes happen asynchronously after an API request completes.

Examples include:

verification results
capability activation
new or updated requirements
account restrictions

Without webhooks, your platform may not detect these changes in a timely manner.

Example event

Example payload

{
  "type": "account.updated",
  "data": {
    "object": {
      "id": "01KN7T8K7WRF9C8MF1CA4KPM6Z",
      "requirements": {
        "currently_due": [
          "company.tax_id"
        ]
      }
    }
  }
}

Delivery model

Webhook events are notifications that a resource has changed.

Your platform should treat the event as a signal to fetch the latest account state.

Do not rely only on the event payload when making operational decisions. Fetch the latest resource from the API before updating platform state.

Handling strategy

Receive the event

Accept the webhook request and verify that it is authentic.

Store it idempotently

Ensure duplicate deliveries do not produce duplicate processing.

Fetch the latest account

Retrieve the most recent account state using the account identifier from the event.

Re-evaluate platform state

Update onboarding status, requirements, and operational readiness in your system.

Key events

account.updated

Sent when a connected account changes.

Use this event to detect:

new requirements
verification progress
changes to operational readiness
capability transitions

capability.updated

Sent when a capability changes state.

Use this event to monitor capability activation or restriction.

Best practices

Process webhook events idempotently
Fetch the latest account state before taking action
Keep webhook handlers fast and reliable
Use webhook processing to update user-facing onboarding progress

Recommendation

Webhooks should be treated as required infrastructure for any platform-managed account integration.

They are essential for keeping your system aligned with the latest account state.

Overview

Testing