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.

ActionEndpoint
Create a subscriptionPOST /api/v1/notifications/subscriptions
Retrieve a subscriptionGET /api/v1/notifications/subscriptions/{subscription_uuid}
List all subscriptionsGET /api/v1/notifications/subscriptions
Update a subscriptionPUT /api/v1/notifications/subscriptions/{subscription_uuid}
Delete a subscriptionDELETE /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 POST request 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 2xx status within 10 seconds. If you don't, Harbor sends it again.

Create a Subscription

POST /api/v1/notifications/subscriptions

  • Required: endpoint, your HTTPS URL, and notification_types, the events to send.
  • Use ["*"] to receive every event, or list specific events or groups such as transfer.*. 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
endpoint and notification_types are 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 2xx within 10 seconds. Harbor retries a non-2xx reply or a timeout.
  • A 404 reply 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.


Did this page help you?