Webhooks Documentation

Webhooks

Handle real-time events from PayAiML in your application with secure webhook endpoints.

How Webhooks Work

Event Occurs

A payment is completed, fails, or another event happens in your PayAiML account.

Webhook Sent

PayAiML sends an HTTP POST request to your configured webhook endpoint.

Process Event

Your application receives and processes the webhook to update your system.

Common Webhook Events

Payment Events
Events related to payment processing
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • charge.succeeded
  • charge.dispute.created
Subscription Events
Events for recurring billing
  • customer.subscription.created
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed

Implementation

Webhook Endpoint
Create a webhook endpoint to receive events
const express = require('express');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['payaiml-signature'];
  
  let event;
  try {
    event = payaiml.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    console.log('Webhook signature verification failed.', err.message);
    return res.status(400).send('Webhook Error: ' + err.message);
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('PaymentIntent was successful!');
      break;
    default:
      console.log('Unhandled event type ' + event.type);
  }

  res.json({received: true});
});
Signature Verification
Verify webhook signatures for security
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Best Practices

Security
  • • Always verify webhook signatures
  • • Use HTTPS endpoints only
  • • Implement idempotency
  • • Handle duplicate events gracefully
Performance
  • • Respond quickly (within 20 seconds)
  • • Process events asynchronously
  • • Return 2xx status codes
  • • Implement retry logic

Ready to implement webhooks?

Start receiving real-time events from PayAiML in your application.