Webhooks

Receiving an event

To receive an event, you need to create an unauthenticated POST endpoint in your application. The event object is sent as JSON in the request body.

// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request body
    const eventType = req.body.event;
    const eventData = req.body.data;
    // Do something with event
    res.sendStatus(200);
});

Supported events

Collect & Onramp

Event	Description
`voucher.created`	A voucher request was successfully created on Ventogram and payment is expected
`voucher.updated`	A voucher payment was received on Ventogram
`voucher.redeemed`	Voucher was successfully redeemed
`verification.success`	This event is raised if a user BVN verification is successful
`verification.failed`	This event is raised if a user BVN verification fails

{
  "event": "voucher.created",
  "data": {
    "id": string;
    "email": string;
    "amount": number;
    "fullname": string;
    "fee": number;
    "wavedFee": number;
    "feeBearer": string;
    "merchant": string;
    "currency": string;
    "paymentExpiresAt": date-time;
    "memo": string;
  },
  "signature": string;
}

{
  "event": 'voucher.updated';
  "data": {
    "id": string;
    "merchant": string;
    "fee": number;
    "currency": string;
    "expectedAmount": number;
    "receivedAmount": number;
    "email": string;
    "waivedFee": number;
    "feeBearer": string;
    "completedAt": 'date-time';
    "resolvedAmount": number;
    "voucherCode": string;
  };
  "signature": string;
}

{
  "event": 'voucher.redeemed';
  "data": {
    "id": string;
    "email": string;
    "fee": number;
    "wavedFee": number;
    "amount": number;
    "voucherCode": string;
    "reference": string;
    "merchant": string;
    "currency": string;
    "feeBearer": string;
    "toAmount": number;
    "fromAmount": number;
    "fromCurrency": string;
    "toCurrency": string;
    "rate": number;
    "previousBalance": number;
    "currentBalance": number;
    "voucherValue": number;
    "voucherValueCurrency": string;
  };
  "signature": string;
}

{
  "event": "verification.success";
  "data": {
    "id": string;
    "email": string;
    "firstName": string;
    "lastName": string;
    "merchant": string;
    "verificationMethod": string;
  },
  "signature": string;
}

{
  "event": "verification.failed",
  "data": {
    "id": string;
    "email": string;
    "firstName": string;
    "lastName": string;
    "merchant": string;
    "verificationMethod": string;
    "reason": string;
  },
  "signature": string;
}

Payout & Offramp

Event	Description
`Payment Created`	A payment request was successfully initiated and payment is expected
`Payment Updated`	Payment was successfully received
`Transaction updated`	A withdrawal request was started and its state is being updated.

{
  event: 'Payment created';
  data: {
    businessId: string;
    reference: string;
    incomingAmount: number;
    incomingCurrency: string;
    outgoingAmount: number;
    outgoingCurrency: string;
    confirmedAmount: number;
    unconfirmedAmount: number;
    expTime: date-time;
    address: string;
    customerEmail: string;
    state: string;
    paymentType: string;
    account: string;
    rate: number;
    outgoingTransactions: object;
    threadTS: string;
    senderUsername: string;
  };
}

{
  event: 'Payment updated';
  data: {
    businessId: string;
    transactions: object;
    outgoingTransactions: object;
    expTime: string;
    reference: string;
    paymentType: string;
    confirmedAmount: number;
    unconfirmedAmount: number;
    incomingAmount: number;
    outgoingCurrency: string;
    incomingCurrency: string;
    rate: number;
    address: string;
    state: string;
    account: string;
    customerEmail: string;
    outgoingAmount: number;
    threadTS: string;
  	resolveId?: string;
  };
}

{
  event: "Transaction updated"
  data:{
    transactionId: string;
    sender: string;
    isFromRegUser: boolean;
    prevBalance: number;
    type: string;
    status: string;
    date: string;
    currency: string;
    amount: number;
    username: string;
    businessId: string;
    fee: number;
    sessionId: string;
    reference?: string;
    failureReason?: string
  }
}

Verifying event source

Every event dispatched by Partna includes a signature property within the payload. The value of this property represents an HMAC SHA256 signature of the event payload, which has been signed using our RSA private key.

Public keys for event data verification

Collect & Onramp

Staging

Production

To verify the signature using our RSA public key, follow the steps below:

import crypto from 'crypto';

const verfyVentogramEvent = (payload: string, signature: string) => {
  res.sendStatus(200);
  const ventogramEventPublicKey = config.ventogramEventPublicKey;

  return crypto.verify(
    'sha256',
    Buffer.from(payload),
    {
      key: ventogramEventPublicKey,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
    },
    Buffer.from(signature, 'base64')
  );
}

const ventogramEventHandler = async (req, res) => {
  const isSignatureValid = verfyVentogramEvent(JSON.stringify(req.body.data), req.body.signature);
  if (!isSignatureValid) {
    return;
  }
  // ... other processing goes here
}

Payout & Offramp

Staging

Production

To verify the signature using our RSA public key, follow the steps below:

import crypto from 'crypto';

const verfyCoinprofileEvent = (payload: string, signature: string) => {
  const publicKey = config.coinprofileEventPublicKey;

  return crypto.verify(
    'sha256',
    Buffer.from(payload),
    {
      key: publicKey,
      padding: crypto.constants.RSA_PKCS1_PSS_PADDING,
    },
    Buffer.from(signature, 'base64')
  );
}

const coinprofileEventHandler = async (req, res) => {
  res.sendStatus(200);
  const isSignatureValid = verfyCoinprofileEvent(JSON.stringify(req.body.data), req.body.signature);
  if (!isSignatureValid) {
    return;
  }
  // ... other processing goes here
}

Overview

Use cases

Receiving an event

Supported events

Verifying event source

Public keys for event data verification

Collect & Onramp

Payout & Offramp

​Receiving an event

​Supported events

​Verifying event source

​Public keys for event data verification

​Collect & Onramp

​Payout & Offramp

Receiving an event

Supported events

Verifying event source

Public keys for event data verification

Collect & Onramp

Payout & Offramp