Webhooks

GetPaidHQ has two webhook surfaces:

Outbound webhook subscriptions - GetPaidHQ sends events to your app.
Payment-provider receiver - Paystack and Checkout.com send payment events to GetPaidHQ.

Outbound webhook subscriptions

Create a webhook subscription

POST https://api.getpaidhq.com/api/webhooks

curl https://api.getpaidhq.com/api/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/getpaidhq",
    "events": ["payment.succeeded", "payment.failed"],
    "secret": "whsec_..."
  }'

Body

url string required - Public HTTPS endpoint.
events string[] required - Event names to subscribe to.
secret string - Optional signing secret.

Webhook URLs are rejected if they resolve to loopback, private, or link-local addresses.

Delivery

GetPaidHQ sends a POST request to the configured URL with JSON body:

{
  "topic": "payment.succeeded",
  "data": {}
}

When a subscription has secret, GetPaidHQ includes:

X-Signature: <hex encoded HMAC-SHA256>
X-Timestamp: 2026-06-17T10:30:00Z
Content-Type: application/json

Verify X-Signature against the raw request body with your webhook secret.

List webhook subscriptions

GET https://api.getpaidhq.com/api/webhooks

The current implementation keeps this route for API compatibility and returns an empty list until webhook subscription listing is fully wired.

Payment-provider receiver

POST https://api.getpaidhq.com/api/notify?p=Paystack
POST https://api.getpaidhq.com/api/notify?p=CheckoutDotCom

This endpoint is public because providers authenticate with their own signature headers:

Paystack: X-Paystack-Signature
Checkout.com: Cko-Signature

GetPaidHQ verifies the provider signature against the raw request body before processing payment success or refund events.

Not currently exposed

The current OpenAPI spec does not expose webhook update, delete, retrieve, or test-event endpoints.