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`	ID of this delivery. It is the same on every retry of the same event, so use it to deduplicate
`X-Hyparrow-Event`	The event name, the same value as `event` in the body
`X-Hyparrow-Timestamp`	Unix seconds when this attempt was sent. Fresh on every attempt
`X-Hyparrow-Signature`	HMAC-SHA512 of the raw body (present once a secret is set)
`X-Hyparrow-Signature-256`	HMAC-SHA256 of `<X-Hyparrow-Timestamp>.<raw body>` (present once a secret is set). Use this one to reject replays

A delivery is acknowledged by 200, 201, 202 or 204. Anything else, or no answer within 30 seconds, is retried: the first attempt is immediate, then retries follow after 1m, 5m, 30m, 2h and 24h, for 6 attempts in total over roughly 26.5 hours. After the last one the delivery is marked failed and stays visible in delivery history.

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.

Timestamped signature (recommended)

X-Hyparrow-Signature covers only the body, so a captured delivery would still verify if someone replayed it later. X-Hyparrow-Signature-256 closes that gap. It is the lowercase hex HMAC-SHA256, keyed with the same webhook secret, of the string:

<value of X-Hyparrow-Timestamp> + "." + <raw request body>

To verify:

Read X-Hyparrow-Timestamp and reject the request if it is more than 5 minutes from your clock. Every attempt, including a retry, is signed when it is sent, so a genuine delivery is always fresh.
Compute the HMAC-SHA256 over timestamp + "." + rawBody and compare it to X-Hyparrow-Signature-256 in constant time.
Deduplicate on X-Webhook-ID, which stays the same across retries of one event.

const crypto = require("crypto");

function verify256(rawBody, headers, secret, toleranceSeconds = 300) {
  const ts = headers["x-hyparrow-timestamp"];
  const sig = headers["x-hyparrow-signature-256"];
  if (!ts || !sig) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(ts + "." + rawBody)
    .digest("hex");
  return sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hmac, hashlib, time

def verify256(raw_body: bytes, headers, secret: str, tolerance: int = 300) -> bool:
    ts = headers.get("X-Hyparrow-Timestamp")
    sig = headers.get("X-Hyparrow-Signature-256")
    if not ts or not sig or abs(time.time() - int(ts)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Both headers are sent on every signed delivery, so an integration already verifying X-Hyparrow-Signature keeps working unchanged.

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 timestamp, and a data object. On transfer, subscription and test events timestamp is Unix seconds (a number); on payroll events it is an RFC 3339 string. For a single clock to check against, use the X-Hyparrow-Timestamp header, which is Unix seconds on every event. 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.

Payroll

Bulk salary runs emit four events. Item events carry both the item’s own transferCode and the batchReference, so you can reconcile per employee or per run without keeping your own mapping between the two. See Payroll.

Event	When
`payroll.batch.approved`	Funds reserved, the run has started
`payroll.item.settled`	One beneficiary was confirmed credited
`payroll.item.failed`	One beneficiary payment did not go through
`payroll.batch.completed`	Every item reached a terminal state

{
  "event": "payroll.item.settled",
  "timestamp": "2026-08-25T09:14:07Z",
  "data": {
    "batchReference": "PRL20260820K7XQ2M",
    "clientReference": "payroll-aug-2026",
    "transferCode": "23191775370145881",
    "employeeRef": "EMP001",
    "beneficiaryName": "Adaobi Nwosu",
    "accountNumber": "0123456789",
    "bankCode": "044",
    "amount": 25000000,
    "fee": 5000,
    "status": "delivered",
    "responseCode": "90000",
    "settledAt": "2026-08-25T09:14:05Z"
  }
}

As with a single transfer, an item reaching sent is not a confirmed credit — that is the local debit record. payroll.item.settled is what confirms delivery.

Outbound transfer settlement

transfer.settled and transfer.failed tell you the final outcome of a payout you initiated with POST /money-transfer/send. They fire only once the outcome is known for certain. transfer.reversed tells you money for a transfer was credited back to your wallet.

Event	When
`transfer.settled`	The beneficiary was credited
`transfer.failed`	The transfer was declined downstream
`transfer.reversed`	The principal (and fee, if one was charged) was credited back to your wallet

Hyparrow asks the processor for the outcome of recent transfers every 5 minutes, starting 5 minutes after the send, so a settled or failed event normally arrives within about 10 minutes. A transfer the processor cannot see yet is asked about again after 15 minutes, 1 hour, 6 hours and then daily. This matters because the status returned by POST /money-transfer is written when your wallet is debited, which happens before the transfer is submitted downstream. It confirms the debit, not the delivery. These events are what confirm delivery.

{
  "event": "transfer.settled",
  "timestamp": 1751277600,
  "data": {
    "transactionId": "9c8b7a65-4d3e-2f1a-0b9c-8d7e6f5a4b3c",
    "reference": "23191775370145881",
    "transferCode": "23191775370145881",
    "clientReference": "your-own-ref-123",
    "status": "success",
    "amount": 12600,
    "fee": 3500,
    "currency": "NGN",
    "recipientAccount": "0123456789",
    "recipientBank": "058",
    "recipientName": "Ada Obi",
    "provider": {
      "name": "interswitch",
      "transactionResponseCode": "90000",
      "transactionRef": "MBP|LOC|CA|OPA|AC|050426072228|NAPUPQVT",
      "transactionId": 8462913,
      "responseMessage": "Successful",
      "polledAt": "2026-08-15T10:22:41Z"
    }
  }
}

The provider object is the upstream processor’s own record, passed through unmodified so you can verify the outcome independently rather than taking our word for it:

transactionResponseCode — 90000 means the beneficiary was credited. Any other value on a transfer.failed event is the decline reason (for example 90051, insufficient funds).
transactionRef — the bank-traceable reference. Quote this when querying a beneficiary bank.
transactionId — the processor’s record id.

amount is the principal and fee is the fee charged on top of it, both in kobo, so each can be posted as its own ledger entry.

Set clientReference on your POST /money-transfer/send request and it is echoed back on these events, so you can match a settlement to your own record without storing the transferCode.

Reversals

transfer.reversed fires whenever money for a transfer comes back to your wallet:

At submission. If the processor refuses a transfer outright, the send returns an error, the principal is credited straight back and no fee is charged. transfer.reversed confirms the credit with reason: "provider_rejected".
After a decline. A transfer.failed debit is reviewed and then reversed, principal and fee. transfer.reversed fires when that happens, with reason: "manual_reversal". Until then the debit stands; contact support if a failed transfer has not been reversed.

{
  "event": "transfer.reversed",
  "timestamp": 1751278200,
  "data": {
    "transactionId": "9c8b7a65-4d3e-2f1a-0b9c-8d7e6f5a4b3c",
    "reference": "23191775370145881",
    "transferCode": "23191775370145881",
    "clientReference": "your-own-ref-123",
    "reversalReference": "REV_23191775370145881",
    "amount": 12600,
    "principalReturned": 12600,
    "feeReturned": 3500,
    "totalReturned": 16100,
    "currency": "NGN",
    "reason": "manual_reversal",
    "reversedAt": "2026-08-15T11:02:10Z"
  }
}

Post totalReturned as the reversing entry against the original clientReference. The reversal also appears in GET /transactions and the statement export as a credit row with reference REV_<transferCode>, carrying the same clientReference.

Payroll items do not use transfer.reversed. Their outcomes come on payroll.item.* events and their money returns through the batch reservation.

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

Timestamped signature (recommended)

Send a test webhook

Example event payload

Payroll

Outbound transfer settlement

Reversals

Customer email preference

Delivery history

​Overview

​Configure your webhook URL

​View current settings

​Generate a signing secret

​Verifying the signature

​Timestamped signature (recommended)

​Send a test webhook

​Example event payload

​Payroll

​Outbound transfer settlement

​Reversals

​Customer email preference

​Delivery history

Overview

Configure your webhook URL

View current settings

Generate a signing secret

Verifying the signature

Timestamped signature (recommended)

Send a test webhook

Example event payload

Payroll

Outbound transfer settlement

Reversals

Customer email preference

Delivery history