Webhooks

​

Webhook Structure

{
  "type": "session.created",
  "timestamp": "2023-06-01T12:05:00Z",
  "data": {
    // Event-specific data
  }
}

• type: Event type (e.g., session.created, payment.succeeded, deposit.succeeded)
• timestamp: ISO 8601 timestamp when the event occurred
• data: Event-specific payload containing the relevant entity data

​

Webhook Events

​

Payment Events

​

Wallet Events

​

Webhook Signature Verification

​

Verification

import { Webhook } from "standardwebhooks";

const wh = new Webhook(process.env.WEBHOOK_SECRET);

function handleWebhook(req: Request) {
  const payload = wh.verify(req.body, req.headers);

  switch (payload.type) {
    case 'session.paid':
      handleSessionPaid(payload.data);
      break;
    case 'payment.succeeded':
      handlePaymentSuccess(payload.data);
      break;
    case 'refund.succeeded':
      handleRefundSuccess(payload.data);
      break;
    case 'deposit.succeeded':
      handleDepositSuccess(payload.data);
      break;
  }
}

​

Idempotency

const webhookId = req.headers['webhook-id'];

if (await isProcessed(webhookId)) {
  return; // Skip duplicate
}

// ... verify and process

await markProcessed(webhookId);

​

Webhook Configuration

1. Webhook URL: The endpoint where ToffeePay will send webhooks
2. Webhook Secret: Used to sign webhook payloads (can be rotated)
3. Event Selection: Choose which events to receive (payments, refunds, deposits, or all)

​

Best Practices

1. Always verify signatures: Never process webhooks without signature verification
2. Handle duplicate events: While rare, webhooks may be sent multiple times — use the webhook-id header for idempotency
3. Respond quickly: Return a 200 status code within 10 seconds to acknowledge receipt
4. Retry logic: ToffeePay will retry failed webhooks, but implement your own retry logic for critical operations
5. Log webhook events: Keep audit logs of all webhook events for debugging and compliance
6. Use HTTPS: Always use HTTPS endpoints for webhook URLs

​

Troubleshooting

​

Common Issues

• Signature verification fails: Check that you’re using the correct webhook secret and following the verification steps exactly
• Timeout errors: Ensure your webhook endpoint responds within 10 seconds
• Missing webhooks: Check your webhook URL configuration and ensure your endpoint is accessible

​

Testing Webhooks

ngrok http 3000