Skip to main content
Hop posts a signed JSON event to your HTTPS endpoint when a payin, payout or transfer changes state.

​
How webhooks work

1

Register Endpoint

Create a webhook endpoint in your application and register its HTTPS URL with Hop
2

Event Occurs

Something happens on your Hop account, for example a payout completes
3

Webhook Sent

We send a signed HTTP POST request to your endpoint with the event envelope
4

Acknowledge

Your endpoint returns a 2xx status code to confirm receipt

​
Available Events

These nine names are the complete set the API accepts. Any other name is rejected when you create or update an endpoint.

​
Payin Events

  • payin.received: funds credited to an account
  • payin.returned: reserved; accepted on a subscription but not emitted today

​
Payout Events

  • payout.created: a payout was created
  • payout.completed: a payout completed
  • payout.failed: a payout failed or was cancelled. There is no separate cancellation event: a cancelled payout arrives as payout.failed with data.status set to cancelled

​
Transfer Events

  • transfer.completed: a transfer between balances on the same account completed
  • transfer.failed: reserved; accepted on a subscription but not emitted today

​
Account Events

  • account.created: an account was opened, either the default account Hop provisions when your customer is approved or an end-customer account created through the API
  • account.updated: Hop changed the account’s status. Your own updates through the API do not raise it

​
Payout Destination Events

  • payout_destination.updated: Hop changed a payout destination, for example a wallet passing or failing review, or a correction to its details. Your own changes through the API do not raise it
A returned payout has no event of its own and produces no webhook. See Webhook Events for the envelope, the payload of each event, and full examples.

​
Getting Started

  1. Create a webhook endpoint via the API
  2. Verify signatures to authenticate incoming webhooks
  3. Follow best practices for reliable processing