Developer Tools

Webhooks

Webhooks allow your application to react to events that happen in your Kopo Pay account, like successful payments, subscription renewals, or dispute updates.

Security Best Practice

Always verify webhook signatures to ensure requests are coming from Kopo Pay. This prevents attackers from spoofing events to your server.

Set up your endpoint

Create a route on your server that accepts POST requests with a JSON body. This endpoint will receive event data from Kopo Pay.

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['kopopay-signature'];
  let event;

  try {
    event = kopopay.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }
  // Handle the event
  response.send();
});

Handle specific events

Use a switch statement to handle the event types your application cares about. Always return a 200 OK response quickly.

switch (event.type) {
  case 'payment_intent.succeeded':
    const paymentIntent = event.data.object;
    // Fulfill the purchase...
    break;
  case 'payment_method.attached':
    const paymentMethod = event.data.object;
    // Handle PM attachment...
    break;
  default:
    console.log(`Unhandled event type ${event.type}`);
}

Register your endpoint

Go to the Developer Dashboard or use the API to register your webhook URL and select the events you want to receive.

const webhookEndpoint = await kopopay.webhookEndpoints.create({
  url: 'https://example.com/webhook',
  enabled_events: [
    'payment_intent.succeeded',
    'payment_intent.payment_failed',
  ],
});