Webhooks
Get notified when customers, onboarding, transfers and accounts change, by subscribing an HTTPS endpoint to Harbor events.
Webhooks let Harbor notify your system when something changes, such as a Customer being verified or a transfer completing.
| Action | Endpoint |
|---|---|
| Create a subscription | POST /api/v1/notifications/subscriptions |
| Retrieve a subscription | GET /api/v1/notifications/subscriptions/{subscription_uuid} |
| List all subscriptions | GET /api/v1/notifications/subscriptions |
| Update a subscription | PUT /api/v1/notifications/subscriptions/{subscription_uuid} |
| Delete a subscription | DELETE /api/v1/notifications/subscriptions/{subscription_uuid} |
How it works:
- You create a subscription. Tell Harbor your endpoint URL and which events you want. See Create a Subscription.
- Harbor sends you events. When one of those events happens, Harbor sends a
POSTrequest with the details to your endpoint. - You check that it's really from Harbor. Each request is signed, so you can confirm it wasn't faked. See Verify Signatures.
- You reply to confirm you got it. Reply with any
2xxstatus within 10 seconds. If you don't, Harbor sends it again.
Create a Subscription
POST /api/v1/notifications/subscriptions
- Required:
endpoint, your HTTPS URL, andnotification_types, the events to send. - Use
["*"]to receive every event, or list specific events or groups such astransfer.*. See Events for the full list.
curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"endpoint": "{{ENDPOINT_URL}}",
"notification_types": ["*"]
}'{
"data": {
"id": 236,
"uuid": "sub_7281f3ea-bdf1-4c67-9a2d-511cada546d5",
"name": "Transactions Webhook",
"endpoint": "https://yourserver.com/webhook",
"enabled": true,
"notification_types": [
"*"
],
"restricted": false,
"callback_secret": "whs_xxxxxxxxxxxxxxxx",
"created_at": "2026-10-05T07:34:49.000000Z",
"updated_at": "2026-10-05T07:34:49.000000Z"
}
}- Save the
callback_secret. It is the signing secret you use to verify each webhook. - New subscriptions are named
Transactions Webhook. To rename one, use Update a Subscription.
Retrieve a Subscription
GET /api/v1/notifications/subscriptions/{subscription_uuid}
Returns one subscription. The response has the same fields as Create a Subscription.
curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions/{{SUBSCRIPTION_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'List All Subscriptions
GET /api/v1/notifications/subscriptions
Returns your subscriptions, 15 per page.
curl --location --request GET 'https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions?page={{PAGE}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'{
"data": [
{
"id": 236,
"uuid": "sub_7281f3ea-bdf1-4c67-9a2d-511cada546d5",
"name": "Transactions Webhook",
"endpoint": "https://yourserver.com/webhook",
"enabled": true,
"notification_types": ["*"],
...
}
],
"links": {
"first": "https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions?page=1",
"last": null,
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"path": "https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions",
"per_page": 15,
"to": 1
}
}To get the next page, call links.next. It is null on the last page.
Update a Subscription
PUT /api/v1/notifications/subscriptions/{subscription_uuid}
Renames a subscription, or turns it on or off. Send both name and enabled every time.
curl --location --request PUT 'https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions/{{SUBSCRIPTION_UUID}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{Idempotency-Key}}' \
--data-raw '{
"name": "{{NAME}}",
"enabled": {{ENABLED}}
}'The response returns the updated subscription.
You can't change the endpoint or events
endpointandnotification_typesare ignored on update. To change them, create a new subscription and delete the old one.
Delete a Subscription
DELETE /api/v1/notifications/subscriptions/{subscription_uuid}
curl --location --request DELETE 'https://harbor-sandbox.owlpay.com/api/v1/notifications/subscriptions/{{SUBSCRIPTION_UUID}}' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}'{
"message": "The webhook subscription was deleted successfully.",
"data": null
}Receive Webhooks
Harbor sends each event as a POST request with a JSON body. The fields sit at the top level, and event tells you which event it is:
{
"uuid": "transfer_Tn5n0O5cBNVYN3KwOXMU43PJe3xPmsXZby54gcVJ",
"event": "transfer.status.completed",
"object": "transfer",
"status": "completed",
...
}Each request has a harbor-signature header. Always check it before you trust the request. See Verify Signatures.
Handling webhooks:
- Reply with any
2xxwithin 10 seconds. Harbor retries a non-2xxreply or a timeout. - A
404reply is treated as a dead endpoint and isn't retried. - The same event can arrive more than once, so make your handler safe to run twice.
- Ignore fields you don't recognize. Harbor may add new fields.
For every event and an example payload, see Events.
Updated about 1 month ago