Endpoint Design

• Make your webhook endpoint idempotent (safe to call multiple times).
• Process webhooks asynchronously to avoid timeouts.
• Log all webhook deliveries for debugging purposes.
• Implement proper error handling and monitoring.

Security

• Always use HTTPS for your webhook endpoints.
• Verify webhook authenticity using the provided authentication method.
• Store authentication credentials securely.

Reliability

• Respond quickly (under 30 seconds) to avoid timeouts.
• Return appropriate HTTP status codes.
• Monitor webhook delivery success rates.

Example Integration

// Express.js example
app.post('/webhooks/funding-deposit-funded', (req, res) => {
  const payload = req.body;
  
  // Verify authentication (implement based on your chosen method)
  if (!verifyAuthentication(req)) {
    return res.status(401).send('Unauthorized');
  }
  
  // Process the webhook
  console.log('Funding deposit funded:', {
    tenantSlug: payload.tenantSlug,
    fundingDepositId: payload.fundingDepositId,
    status: payload.fundingStatus
  });
  
  // Update your system accordingly
  updateFundingDepositStatus(payload.fundingDepositId, payload.fundingStatus);
  
  // Return success response
  res.status(200).send('OK');
});

Test Your Integration

Complete the steps below to verify your webhook integration results.

1. Create a test subscription pointing to your webhook endpoint.
2. Trigger a funding deposit event in your test environment.
3. Verify your endpoint receives the webhook with the correct payload.
4. Confirm that your response handling returns appropriate HTTP status codes.
5. Test your authentication method by sending requests with invalid credentials.

Troubleshooting

See our recommendations for resolving common webhook issues below.

Issue 1: The webhook was not received.

• Verify that your subscription is active and configured correctly. See our Webhook Setup Guide for details.
• Check that your endpoint is accessible from external networks.
• Ensure your endpoint returns 2xx status codes.
• Review your server logs for any errors that may have occurred during processing.

Issue 2: Authentication failed.

• Verify that the credentials in your subscription match your endpoint's expectations.
• Check that the authentication headers are being processed correctly.
• Ensure that your credentials have not expired or been rotated.

Issue 3: There was an issue with the webhook payload.

• Confirm that your endpoint can accept the JSON payload format.
• Check for any unexpected field names or data types.
• Validate that your parsing logic matches the documented schema.

Support

For additional support with webhook setup, consult your existing API documentation or send us your request on the Customer Support Portal with your subscription ID and specific error details.