Webhooks

Overview

Webhooks let Hyparrow push events to your server in real time instead of you polling the API. When something happens — a subscription renewal is paid, a customer transaction completes — Hyparrow sends an HTTP POST with a JSON payload to the URL you configure. Each webhook request carries these headers:

Header	Description
`Content-Type`	Always `application/json`
`User-Agent`	`Hyparrow-Webhook/1.0`
`X-Webhook-ID`	Unique ID for this delivery attempt
`X-Hyparrow-Signature`	HMAC signature of the raw body (present once a secret is set)

Deliveries are retried automatically on failure with a backoff of 1m, 5m, 30m, 2h, 24h — up to 5 attempts. Your endpoint should return a 2xx status to acknowledge receipt.

Base URL: https://api.hyparrow.cloud/api/v1Webhook settings endpoints are authenticated with your API key pair:

X-API-Key: pk_live_xxxxxxxxxxxx
X-API-Secret: sk_live_xxxxxxxxxxxx

Point your webhook URL at a sandbox listener and configure it from https://sandbox.hyparrow.cloud/api/v1 with pk_test_ keys to safely exercise deliveries.

Configure your webhook URL

POST /webhooks/settings sets the URL Hyparrow delivers events to. You may also pass an optional allowedIps list to restrict which source IPs your endpoint accepts.

Set your URL

POST your HTTPS endpoint to /webhooks/settings.

Generate a signing secret

Call /webhooks/settings/secret so deliveries are signed.

Verify the signature on every request

Recompute the HMAC over the raw body and compare it to X-Hyparrow-Signature.

Send a test event

Use /webhooks/settings/test to confirm end-to-end delivery.

curl -X POST https://api.hyparrow.cloud/api/v1/webhooks/settings \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.acme-store.com/hooks/hyparrow",
    "allowedIps": ["203.0.113.10"]
  }'

{
  "success": true,
  "message": "Webhook settings updated successfully",
  "data": {
    "webhookUrl": "https://api.acme-store.com/hooks/hyparrow",
    "allowedIps": ["203.0.113.10"]
  }
}

webhookUrl must be a valid URL. An invalid value returns 400.

View current settings

GET /webhooks/settings returns your configured URL, allowed IPs, whether a secret is set (with a masked preview), and your customer-email preference.

curl https://api.hyparrow.cloud/api/v1/webhooks/settings \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "webhookUrl": "https://api.acme-store.com/hooks/hyparrow",
    "allowedIps": ["203.0.113.10"],
    "hasSecret": true,
    "secretMasked": "a1b2c3d4...8e7f6a5b",
    "handleCustomerEmails": false
  }
}

Generate a signing secret

POST /webhooks/settings/secret generates a new signing secret and stores it. The full secret is returned only once — store it securely.

curl -X POST https://api.hyparrow.cloud/api/v1/webhooks/settings/secret \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "message": "Webhook secret generated successfully. Store this securely - it will not be shown again.",
  "data": {
    "secret": "a1b2c3d4e5f6...0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e7f6a5b"
  }
}

Generating a new secret replaces any previous one. Update your verification code immediately so you don’t reject incoming deliveries.

Verifying the signature

When a secret is set, every delivery includes an X-Hyparrow-Signature header. It is an HMAC-SHA512 of the raw request body, keyed with your webhook secret and hex-encoded. To verify, recompute the HMAC over the exact bytes you received and compare it to the header using a constant-time comparison. Reject the request if they differ.

const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha512", secret)
    .update(rawBody) // the raw bytes, before JSON.parse
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha512).hexdigest()
    return hmac.compare_digest(signature_header, expected)

Compute the HMAC over the raw, unparsed body. Re-serializing the parsed JSON can change byte ordering or whitespace and produce a different signature.

Send a test webhook

POST /webhooks/settings/test delivers a sample event to your configured URL so you can validate your endpoint and signature handling.

curl -X POST https://api.hyparrow.cloud/api/v1/webhooks/settings/test \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "message": "Test webhook sent successfully to https://api.acme-store.com/hooks/hyparrow"
}

The payload your endpoint receives looks like:

{
  "event": "test.webhook",
  "timestamp": 1751277000,
  "data": {
    "message": "This is a test webhook from Hyparrow",
    "clientId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  }
}

If no webhook URL is configured, this returns 400 No webhook URL configured.

Example event payload

All events share the same envelope: a top-level event name, a Unix timestamp, and a data object. Here is a subscription.payment.completed event, delivered when a subscription renewal is paid:

{
  "event": "subscription.payment.completed",
  "timestamp": 1751277600,
  "data": {
    "subscriptionId": "5d6e7f80-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "customerId": "c1a2b3c4-d5e6-7a8b-9c0d-1e2f3a4b5c6d",
    "productId": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "amount": 4500.00,
    "currency": "NGN",
    "paidAt": "2026-06-30T11:00:00Z",
    "periodStart": "2026-06-30T11:00:00Z",
    "periodEnd": "2026-07-30T11:00:00Z",
    "reference": "VA-2026-0042",
    "paymentSource": "va"
  }
}

Other events you may receive include checkout.payment.completed (a checkout-link payment landed) and customer.transaction.completed (a customer transaction settled). All follow the same event / timestamp / data envelope, so write your handler to switch on the event field.

Customer email preference

PUT /webhooks/settings/customer-emails controls whether Hyparrow sends transactional emails (invoice receipts, subscription notices) directly to your end customers. Set handleCustomerEmails to false if you prefer to own all customer communication yourself.

curl -X PUT https://api.hyparrow.cloud/api/v1/webhooks/settings/customer-emails \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "handleCustomerEmails": false }'

{
  "success": true,
  "message": "Customer email preference updated",
  "data": { "handleCustomerEmails": false }
}

The handleCustomerEmails field is required and must be a boolean. Omitting it returns 400; an explicit false is accepted and disables customer-facing emails.

Delivery history

GET /webhooks/events returns recent delivery attempts so you can audit what was sent and whether it succeeded. Useful both for debugging and as a polling fallback.

Query param	Description
`limit`	Max events to return (default `50`, capped at `100`)
`since`	RFC3339 timestamp; return events created at or after this time

curl "https://api.hyparrow.cloud/api/v1/webhooks/events?limit=20&since=2026-06-30T00:00:00Z" \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "X-API-Secret: sk_live_xxxxxxxxxxxx"

{
  "success": true,
  "data": [
    {
      "id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
      "clientId": "1a2b3c4d-...",
      "event": "subscription.payment.completed",
      "status": "delivered",
      "attempts": 1,
      "maxAttempts": 5,
      "httpStatus": 200,
      "deliveredAt": "2026-06-30T11:00:01Z",
      "createdAt": "2026-06-30T11:00:00Z"
    },
    {
      "id": "e1d2c3b4-a5f6-7890-1bcd-ef2345678901",
      "clientId": "1a2b3c4d-...",
      "event": "test.webhook",
      "status": "failed",
      "attempts": 5,
      "maxAttempts": 5,
      "httpStatus": 500,
      "lastError": "webhook returned status 500",
      "nextRetryAt": null,
      "createdAt": "2026-06-29T09:15:00Z"
    }
  ]
}

A delivery’s status is one of pending (awaiting a retry), delivered (a 2xx was returned), or failed (exhausted all attempts). Inspect lastError and httpStatus to diagnose failures.

Getting Started

Identity

Customers

Accepting Payments

Payouts & Bills

Commerce

Crypto

Developer

Overview

Configure your webhook URL

View current settings

Generate a signing secret

Verifying the signature

Send a test webhook

Example event payload

Customer email preference

Delivery history

​Overview

​Configure your webhook URL

​View current settings

​Generate a signing secret

​Verifying the signature

​Send a test webhook

​Example event payload

​Customer email preference

​Delivery history

Overview

Configure your webhook URL

View current settings

Generate a signing secret

Verifying the signature

Send a test webhook

Example event payload

Customer email preference

Delivery history