Webhooks deliver real-time notifications to your systems when events happen in HatchPay — a payment is captured, a refund is processed, a transaction is created. Subscriptions are scoped to a business unit, so different business units can route events to different destinations, and each subscription chooses exactly which events it wants. For a conceptual overview, payload format, and the full event catalog, see the Webhooks reference.

Creating a Webhook

A webhook can either be created from the tenant console or by sending a POST to create a subscription under a business unit. At minimum, provide the destination_url HatchPay should call; event_types filters which events trigger it (omit it to receive everything).

POST /v1/webhooks/{business_unit_id}/webhooks

{
    "label": "Webhook - Authorized Transactions",
    "destination_url": "https://example.com/hooks/hatchpay",
    "webhook_auth_info_id": "c2912c8c-2a9e-4e72-b92d-edc15adf9447",
    "event_types": [
        "payment-proxy.transactions.authorize"
    ]
}

Add or Remove Events

Update a subscription to change its destination or the events it listens for. Reference the subscription by its identifier:

PUT /v1/webhooks/{business_unit_id}/webhooks/{bu_webhook_id}

{
    "destination_url": "https://example.com/hooks/hatchpay",
    "event_types": [
        "payment-proxy.transactions.capture"
    ]
}

Deleting a Webhook

DELETE /v1/webhooks/{business_unit_id}/webhooks/{bu_webhook_id}

Authentication Configurations

An authentication configuration lets your endpoint verify that a delivery genuinely came from HatchPay. Create one, then reference its id from a subscription via webhook_auth_info_id.

POST /v1/webhooks/auth-info

{
    "auth_type": "API Credentials",
    "auth_config": {
        "client_id": "abc-123",
        "client_secret": "def-456"
    }
}

Update one with PUT /v1/webhooks/auth-info/{auth_info_id} and remove it with DELETE /v1/webhooks/auth-info/{auth_info_id}. Credentials are encrypted at rest and redacted on standard reads. Supported auth_type values include Custom, Basic Auth, and API Credentials.

Webhook Event Types

Any number of event types can be attached to a subscription. The available events are:

api-key.keys.create
api-key.keys.update
api-key.keys.delete
api-key.keys.assign-roles
api-key.keys.reveal
communication.communications.send
communication.templates.create
business.unit.payment.orchestrator.create
business.unit.payment.orchestrator.update
business.unit.payment.orchestrator.delete
invite-to-pay.codes.create
invite-to-pay.codes.cancel
invite-to-pay.codes.update
payment-proxy.transactions.rescind
payment-proxy.transactions.create
payment-proxy.transactions.authorize
payment-proxy.transactions.update
payment-proxy.transactions.capture
payment-proxy.transactions.inquire
payment-proxy.transactions.void
payment-proxy.transactions.refund
payment-proxy.i2p.resend
payment-proxy.transactions.authorize.and.capture
payment-proxy.transactions.capture.failed
payment-proxy.transactions.refund.failed
payment-proxy.transactions.void.failed
payment-proxy.transactions.authorize.failed
payment-proxy.transactions.authorize.and.capture.failed

Previous: Integrate I2P UI iFrame