App connection events

App connection events use the v1.connection.* prefix and report customer consent or revocation.

Overview

An app connection lets a partner act on behalf of a Hubpay customer that has explicitly granted scoped access. Consent happens asynchronously in the Hubpay Business app, so the partner has no synchronous signal when the outcome lands. We emit a webhook on each connection lifecycle transition so your system learns the moment a connection becomes ACTIVE, is declined, or is later revoked, and can start or stop making scoped on-behalf-of API calls.

---

Event catalogue

Event	When it triggers
v1.connection.accepted	The customer approved the connection in the Hubpay Business app. It is now ACTIVE and the partner can make scoped on-behalf-of calls.
v1.connection.declined	The customer declined the connection request. It will not become active.
v1.connection.revoked	The connection was ended by the partner or the customer. On-behalf-of access has stopped.

All events carry relatedObjectType = connection.

Event flow

1. The partner creates a connection request via Create connection. It starts PENDING: no webhook is emitted yet.
2. The customer opens the deep link and approves or declines. On approval you receive connection.accepted; on decline you receive connection.declined.
3. Once active, if the partner or the customer later ends the connection you receive connection.revoked and on-behalf-of access stops.

---

Additional data

Each connection.* event includes the following properties in the data object. All values are strings.

Field	Type	Events	Description
connectionId	string	All	UUID of the connection. Matches relatedObject.id and the connectionId from the create-connection response.
partnerAccountId	string	All	Account id of the partner that owns the connection. Also the envelope accountId.
customerAccountId	string	When present	Account id of the connected customer. Present once the connection is bound to a customer.
status	string	All	Connection status after the transition: ACTIVE, DECLINED, or REVOKED.
scopes	string	All	Comma-separated list of granted scopes (order not guaranteed), e.g. WALLET_BALANCE_READ,FUNDING_ACCOUNT_READ.

---

Payload examples

connection.accepted

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.connection.accepted",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-06-30T09:30:00Z",
  "data": {
    "connectionId": "11111111-1111-1111-1111-111111111111",
    "partnerAccountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
    "customerAccountId": "22222222-2222-2222-2222-222222222222",
    "status": "ACTIVE",
    "scopes": "WALLET_BALANCE_READ"
  },
  "relatedObject": {
    "id": "11111111-1111-1111-1111-111111111111",
    "type": "connection"
  }
}

connection.declined

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.connection.declined",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-06-30T09:31:00Z",
  "data": {
    "connectionId": "11111111-1111-1111-1111-111111111111",
    "partnerAccountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
    "status": "DECLINED",
    "scopes": "WALLET_BALANCE_READ"
  },
  "relatedObject": {
    "id": "11111111-1111-1111-1111-111111111111",
    "type": "connection"
  }
}

connection.revoked

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "v1.connection.revoked",
  "accountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
  "createdAt": "2026-06-30T15:00:00Z",
  "data": {
    "connectionId": "11111111-1111-1111-1111-111111111111",
    "partnerAccountId": "f5e6d7c8-b9a0-4321-8765-0fedcba98765",
    "customerAccountId": "22222222-2222-2222-2222-222222222222",
    "status": "REVOKED",
    "scopes": "WALLET_BALANCE_READ"
  },
  "relatedObject": {
    "id": "11111111-1111-1111-1111-111111111111",
    "type": "connection"
  }
}

See Event format for the webhook envelope schema.

---

Footnotes

No webhook for PENDING or EXPIRED. A connection request starts PENDING (created by the partner itself, so no notification is needed) and moves to EXPIRED if the customer never acts. Only the accepted, declined, and revoked transitions emit webhooks.

Thin events. Like all Hubpay webhooks these are thin notifications: fetch the authoritative state via Get connection when you receive one.