Webhooks

Listen for real-time events happening in your Tulify account. Configure your webhook URL in the dashboard settings to receive these events.

Verifying Webhooks

To ensure the webhook request originated from Tulify, we include a signature in thex-tulify-signatureheader.

The signature is a HMAC SHA256 hash of the request body using your Webhook Secret.

Node.js Verification Example

import crypto from 'crypto';

const secret = 'whsec_...'; // Your Webhook Secret
const signature = req.headers['x-tulify-signature'];
const payload = JSON.stringify(req.body);

const hash = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (hash === signature) {
  // Request is verified
} else {
  // Invalid request
}

PAYMENT.SUCCESS

Event

Triggered when a payment is successfully verified.

Payload ExampleJSON

{
  "event": "PAYMENT.SUCCESS",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "payload": {
    "reference": "ref_123456789",
    "amount": 5000,
    "currency": "NGN",
    "status": "success",
    "gateway_response": "Approved",
    "paid_at": "2024-01-01T12:00:00.000Z",
    "channel": "card",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    }
  }
}

PAYMENT.REFUNDED

Event

Triggered when a payment is successfully refunded.

Payload ExampleJSON

{
  "event": "PAYMENT.REFUNDED",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "payload": {
    "reference": "ref_123456789",
    "amount": 5000,
    "currency": "NGN",
    "refund_status": "processed",
    "refunded_at": "2024-01-02T10:00:00.000Z"
  }
}