Skip to main content

​
Webhook Overview

Payvessel uses webhooks to deliver real-time notifications when events occur on your account—such as successful payments, wallet funding, or virtual account credits. This allows you to trigger business workflows instantly without polling the API.
Configure webhook endpoints in the Payvessel Dashboard and verify each notification before updating customer balances or order status.

​
Delivery Workflow

1

Event Occurs

A transaction, payout, verification, or account update happens inside Payvessel.
2

Webhook Sent

Payvessel signs the JSON payload with your secret key and sends it to your registered endpoint.
3

Verify & Process

Your server verifies the signature, checks the sender IP, prevents duplicates, and runs business logic.
4

Acknowledge

Return an HTTP 200 response to stop retries. Payvessel retries failed deliveries with exponential backoff.

​
Security Essentials

Hash Verification

Compute an HMAC SHA-512 hash with your secret (PVSECRET-) and compare with the HTTP_PAYVESSEL_HTTP_SIGNATURE header.

Trusted IPs

Accept requests only from Payvessel IPs 3.255.23.38 and 162.246.254.36.

Duplicate Protection

Make webhook handlers idempotent and store processed references.

​
Headers You Will Receive

HeaderDescription
HTTP_PAYVESSEL_HTTP_SIGNATUREHMAC SHA-512 hash of the payload generated with your Payvessel secret
Content-TypeAlways application/json
X-Forwarded-ForPresent when your infrastructure sits behind a proxy—use it to determine the originating IP

​
Webhook Payload Anatomy

Payvessel webhook payloads are JSON objects that include high-level order information and nested objects for the specific resource that changed. A typical transaction notification looks like this: 
{
  "event": "transaction.success",
  "order": {
    "amount": "50000",
    "settlement_amount": "48500",
    "fee": "1500",
    "currency": "NGN",
    "description": "Order #INV-2094",
    "status": "completed"
  },
  "transaction": {
    "reference": "TXN_2024_001",
    "channel": "bank_transfer",
    "status": "success",
    "customer_email": "[email protected]",
    "paid_at": "2024-02-14T10:36:42Z"
  },
  "metadata": {
    "customer_id": "CUST_2983",
    "order_id": "INV-2094"
  }
}
Use the event field to route requests to dedicated handlers. See the Supported Events catalog for the complete list.

​
Delivery Guarantees & Retries

  • At-least-once delivery: Implement idempotency to safely handle duplicates.
  • Retry schedule: Payvessel retries failed deliveries for up to 24 hours with exponential backoff.
  • Timeouts: Respond within 10 seconds; otherwise, the attempt is considered failed and retried.

​
Testing Webhooks Locally

ngrok http 3000
Configure the generated HTTPS URL as your webhook endpoint in the Payvessel Dashboard.

​
Operational Best Practices

  • Log every incoming request body and headers for traceability.
  • Send alerts when webhook deliveries fail repeatedly.
  • Wrap handlers in background jobs if business logic takes longer than a few seconds.
  • Version your webhook handlers together with the API contract.