Webhooks

Receive real-time notifications about payment events

Overview

Webhooks allow you to receive real-time notifications when events occur in your Yassir Payment account. Instead of polling our API for updates, we push event data to your server as they happen.

Important

Always verify webhook signatures before processing events. This ensures the webhook was sent by Yassir and not a malicious third party.

Event Types

Event	Description
`payment.created`	Payment intent was created
`payment.processing`	Payment is being processed
`payment.succeeded`	Payment completed successfully
`payment.failed`	Payment failed
`payment.canceled`	Payment was canceled
`payment.refunded`	Full refund was processed
`payment.partially_refunded`	Partial refund was processed

Setting Up Webhooks

Configure your endpoint

Create an HTTP endpoint on your server to receive webhook events. The endpoint must be publicly accessible and use HTTPS.

Register the webhook

Register your webhook URL in the Yassir merchant dashboard. You will receive a webhook secret for signature verification.

Implement signature verification

Verify the webhook signature before processing:

JavaScript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Handle events

Process the webhook event and return a 2xx response:

JavaScript

app.post('/webhooks/yassir', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailure(event.data);
      break;
  }

  res.status(200).send('OK');
});

app.post('/webhooks/yassir', async (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;

  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailure(event.data);
      break;
  }

  res.status(200).send('OK');
});

Best Practices

Respond to webhooks within 30 seconds
Process webhook data asynchronously for long operations
Handle duplicate events using idempotency
Store processed event IDs to prevent duplicate processing