Webhooks

Afriex sends webhook notifications for key events. The SDK provides a verifier to validate webhook signatures.

Setup

Initialize the SDK with your webhook public key:


const afriex = new AfriexSDK({
  apiKey: 'your-api-key',
  webhookPublicKey: 'your-afriex-public-key'
});

Verify Webhook Signature


app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body; // Raw string body
 
  try {
    const event = afriex.webhooks.verifyAndParse(payload, signature);
    
    // Handle the event
    switch (event.event) {
      case 'customer.created':
        console.log('Customer created:', event.data);
        break;
      case 'TRANSACTION.CREATED':
        console.log('Transaction created:', event.data);
        break;
      case 'PAYMENT_METHOD.CREATED':
        console.log('Payment method created:', event.data);
        break;
    }
 
    res.status(200).send('OK');
  } catch (error) {
    console.error('Invalid signature');
    res.status(400).send('Invalid signature');
  }
});

Event Types

Customer Events

Event	Description
`customer.created`	Customer was created
`customer.updated`	Customer was updated
`customer.deleted`	Customer was deleted

Payload:


{
  event: 'customer.created',
  data: {
    customerId: string,
    name: string,
    email: string,
    phone: string,
    countryCode: string
  }
}

Transaction Events

Event	Description
`TRANSACTION.CREATED`	Transaction was created
`TRANSACTION.UPDATED`	Transaction status changed

Payload:


{
  event: 'TRANSACTION.UPDATED',
  data: {
    transactionId: string,
    customerId: string,
    destinationId: string,
    status: 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | ...,
    type: string,
    sourceAmount: string,
    sourceCurrency: string,
    destinationAmount: string,
    destinationCurrency: string,
    meta: { narration?, invoice?, idempotencyKey?, merchantId? },
    createdAt: string,
    updatedAt: string
  }
}

Payment Method Events

Event	Description
`PAYMENT_METHOD.CREATED`	Payment method was created
`PAYMENT_METHOD.UPDATED`	Payment method was updated
`PAYMENT_METHOD.DELETED`	Payment method was deleted

Payload:


{
  event: 'PAYMENT_METHOD.CREATED',
  data: {
    paymentMethodId: string,
    channel: string,
    customerId: string,
    accountName: string,
    accountNumber: string,
    countryCode: string,
    institution: { institutionId?, institutionName?, institutionCode? },
    recipient: { recipientName?, recipientEmail?, recipientPhone? }
  }
}

Signature Verification Only

If you only want to verify the signature without parsing:


const isValid = afriex.webhooks.verify(payload, signature);
 
if (isValid) {
  const event = JSON.parse(payload);
  // Handle event
}