Webhooks

Register

HTTPS only. The response includes a secret (weh_…).

curl -X POST https://api.puplar.com/webhooks \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourdomain.com/webhooks/puplar" }'

Envelope

Every delivery is { id, type, timestamp, payload }. id is the event id. payload depends on type. Amounts are minor units (kobo/cents). Confirm with GET /transactions/{id}/verify (or the matching retrieve endpoint) before fulfilling.

Events

Event	When	Sample
`virtual_account.deposit`	Bank deposit received	below
`crypto.deposit`	Token deposit received	Crypto
`payment.completed`	Payment succeeded	Payments
`payment.failed`	Payment failed	Payments
`payment.expired`	Payment expired	Payments
`payment.canceled`	Payment canceled	Payments
`collection.completed`	Collection payment succeeded	Collections
`collection.canceled`	Collection canceled	Collections
`refund.initiated`	Refund created	Refunds
`refund.completed`	Refund succeeded	Refunds
`refund.failed`	Refund failed	Refunds
`payout.initiated`	Payout created	Payouts
`payout.completed`	Payout arrived	Payouts
`payout.failed`	Payout failed	Payouts
`payout.canceled`	Payout canceled	Payouts
`invoice.finalized`	Invoice opened for payment	Invoices
`invoice.sent`	Invoice emailed	Invoices
`invoice.paid`	Invoice paid	Invoices
`invoice.voided`	Invoice voided	Invoices

Payload

Example: virtual_account.deposit. payload.id is the transaction id. source is the sender’s bank details when present. payload.status is always completed on this event.

{
  "id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "type": "virtual_account.deposit",
  "timestamp": "2026-07-26T12:00:00.000Z",
  "payload": {
    "id": "64f9b3c4d5e6f7a8b9c0d1e2",
    "status": "completed",
    "method": "bank_transfer",
    "amount": 50000,
    "livemode": true,
    "direction": "credit",
    "currency": "ngn",
    "metadata": {},
    "source": {
      "account_name": "Jane Doe",
      "account_number": "0123456789",
      "bank_name": "Access Bank"
    },
    "customer": "64aa11b2c3d4e5f6a7b8c9d0"
  }
}

Other events use the same envelope. Their payload objects are on the feature guides in the table above.

Verify the signature

Header: X-Signature: sha256=<hmac>. HMAC-SHA256 of the raw body with your webhook secret.

import crypto from 'crypto';

function verifyWebhook(rawBody: Buffer, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length) return false;

  return crypto.timingSafeEqual(a, b);
}

import hmac
import hashlib

def verify_webhook(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Hash the raw request bytes. Do not parse JSON and re-stringify — key order and spacing will break the signature. Non-2xx or timeout → up to 3 retries. Inspect with GET /webhooks/events.

curl -X POST https://api.puplar.com/webhooks/events/resend \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "webhook_id": "64f9b3c4d5e6f7a8b9c0d1e2"
  }'

Action	Endpoint
List	`GET /webhooks`
Update	`PUT /webhooks/{id}`
Delete	`DELETE /webhooks/{id}`
Delivery log	`GET /webhooks/events`
One delivery	`GET /webhooks/events/{id}`
Resend	`POST /webhooks/events/resend`

Getting Started

Feature Guides

Register

Envelope

Events

Payload

Verify the signature

​Register

​Envelope

​Events

​Payload

​Verify the signature

Register

Envelope

Events

Payload

Verify the signature