Webhooks let HatchPay push event notifications to your own systems as activity occurs, so you do not have to poll the API. When an auditable event happens — a transaction is captured, a refund is processed, an I2P code is created — HatchPay delivers an HTTP POST to the destination URL you have registered. Webhook subscriptions are managed by the Webhook service and are scoped to a specific business unit.

For a step-by-step walkthrough of creating your first subscription, see the Webhook Setup tutorial.

Registering a Subscription

Subscriptions are created per business unit so that different business units can route events to different destinations.

POST /v1/webhooks/{business_unit_id}/webhooks

{
    "label": "Order fulfillment listener",
    "destination_url": "https://example.com/hooks/hatchpay",
    "webhook_auth_info_id": "f1e2d3c4-0000-4a1b-9c2d-000000000000",
    "event_types": [
        "payment-proxy.transactions.capture",
        "payment-proxy.transactions.refund"
    ]
}

• destination_url (required) — the HTTPS endpoint HatchPay will POST to.
• label (optional) — a human-readable name for the subscription.
• event_types (optional) — the events that should trigger delivery. Omit it to receive every event type.
• webhook_auth_info_id (optional) — a reference to a stored authentication configuration (see below).

You can list, retrieve, update, and delete subscriptions with GET, PUT, and DELETE on /v1/webhooks/{business_unit_id}/webhooks and /{bu_webhook_id}. The stored secret is redacted on normal reads; use the /reveal variant to retrieve the full value.

Event Types

Events follow a domain.resource.action naming pattern. Common event types include:

• payment-proxy.transactions.create, payment-proxy.transactions.authorize, payment-proxy.transactions.capture, payment-proxy.transactions.void, payment-proxy.transactions.refund, and payment-proxy.transactions.authorize.and.capture
• The corresponding failure events, such as payment-proxy.transactions.capture.failed and payment-proxy.transactions.refund.failed
• invite-to-pay.codes.create, invite-to-pay.codes.update, invite-to-pay.codes.cancel, and payment-proxy.i2p.resend
• business.unit.payment.orchestrator.create, business.unit.payment.orchestrator.update, business.unit.payment.orchestrator.delete
• api-key.keys.create, api-key.keys.update, api-key.keys.delete, api-key.keys.assign-roles
• communication.communications.send, communication.templates.create

Delivery Payload

Each delivery is a JSON document identifying the tenant, the event, and the event-specific payload.

{
    "trace_id": "403225d5-1bf5-47fa-a504-e58e73303635",
    "tenant_id": "4b8fafc0-2011-4e1a-9941-4bf4832f5fb2",
    "event_type": "payment-proxy.transactions.capture",
    "metadata": {
        "payload": { },
        "business_unit_id": "79772e73-7a93-40ba-889f-3bdd37ab1d18"
    },
    "tenant_event_id": "c0ffee00-0000-4000-8000-000000000000"
}

Authenticating Deliveries

To let your endpoint verify that a request genuinely came from HatchPay, attach a stored authentication configuration to the subscription via webhook_auth_info_id. Auth configurations are created and managed under /v1/webhooks/auth-info and support custom headers, basic authentication, and API-credential schemes. Credentials are encrypted at rest and never returned in plain text on standard reads.

Retries & Reliability

Deliveries that do not return a 2xx response are retried with backoff; the number of HTTP attempts per delivery is bounded, and persistently failing deliveries are routed to a dead-letter path for later inspection. Your endpoint should be idempotent, since a delivery may occasionally be retried after a slow success.

Testing Webhooks

During development you can point a subscription’s destination_url at the Webhook Testing service, which receives and logs incoming deliveries so you can inspect the exact payloads HatchPay sends before wiring up your own handler.

Previous: I2P Next: Communications