UniBee webhooks

​

What is UniBee webhook?

• Successful payments (payment.succeeded)
• Invoice creation(invoice.created)
• Subscription Auto-charged(subscription.auto-charge.success)

​

When to use UniBee webhooks?

​

How to use UniBee webhooks?

​

Create Your webhook endpoint (By Admin Portal)

• Go to the Configuration section via the sidebar
• Open the Webhook tab
• Click + to add an endpoint
• Enter the webhook URL
• Choose events what you want
• Click Ok to confirm

• Must be publicly accessible: Your webhook endpoint must be reachable from the internet
• Must use HTTPS: UniBee requires HTTPS URLs for webhook endpoints (HTTP is not supported for security reasons)
• Valid domain: The URL must resolve to a valid server that accepts HTTP POST requests
• Test in Sandbox: For testing, you can use staging servers, cloud functions, or local development tools that expose HTTPS URLs

• Deploy to a staging environment (recommended for production testing)
• Use tunneling tools like ngrok, localtunnel, or similar services
• Ensure the URL remains stable during testing, as webhook events will be sent to the configured URL

​

Access Your webhook logs

• Go to the Configuration section via the sidebar
• Open the Webhooks tab
• Click on the webhook endpoint to see the list of events
• Mouse up to the Request Body And Response , you will see the log detail
• Click the resend icon to repeat event call (optional)

​

Accessing a specific event

• Webhook URL: the URL used to listen to events;
• Msg Id: idempotency Id associated with the event;
• Webhook event: the webhook event used to understand the action triggered;
• Response: the response code (i.e. acknowledgement of receipt);
• Number of retries: if the event failed, the number of retries attempted;
• A JSON snippet with the arguments sent by UniBee

​

Webhook Event Headers

​

Verifying Webhook Requests

• Copy your API key from UniBee Admin Portal (Configuration → Integrations → UniBee API Key)
• Store it securely in your environment variables

app.post('/webhooks/unibee', express.json(), async (req, res) => {
  // Get Authorization header
  const authHeader = req.headers['authorization'];
  const expectedAuth = `Bearer ${process.env.UNIBEE_API_KEY}`;
  
  // Verify API key
  if (authHeader !== expectedAuth) {
    return res.status(401).send('Invalid API key');
  }
  
  // Process webhook event
  const payload = req.body;
  const eventType = req.headers['eventtype'];
  
  // Handle different event types
  switch (eventType) {
    case 'subscription.activate':
      await handleSubscriptionActivate(payload);
      break;
    case 'invoice.paid':
      await handleInvoicePaid(payload);
      break;
    // ... other event types
  }
  
  // Return success response
  res.status(200).send('success');
});

const crypto = require('crypto');

app.post('/webhooks/unibee', express.raw({ type: 'application/json' }), async (req, res) => {
  // Get headers
  const signature = req.headers['x-signature'];
  const algorithm = req.headers['x-signature-algorithm'];
  const eventType = req.headers['eventtype'];
  const eventId = req.headers['eventid'];
  const msgId = req.headers['msg-id'];
  
  // Get raw body as string for signature verification
  const rawBody = req.body.toString();
  
  // Verify HMAC signature
  if (signature && algorithm === 'hmac') {
    const expectedSignature = crypto
      .createHmac('sha256', process.env.UNIBEE_API_KEY)
      .update(rawBody)
      .digest('base64');
    
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
      return res.status(401).send('Invalid signature');
    }
  } else {
    // Fallback to API key verification if signature is not present
    const authHeader = req.headers['authorization'];
    const expectedAuth = `Bearer ${process.env.UNIBEE_API_KEY}`;
    
    if (authHeader !== expectedAuth) {
      return res.status(401).send('Invalid API key');
    }
  }
  
  // Parse JSON payload
  const payload = JSON.parse(rawBody);
  
  // Handle different event types
  switch (payload.eventType || eventType) {
    case 'subscription.activate':
      await handleSubscriptionActivate(payload);
      break;
    case 'invoice.paid':
      await handleInvoicePaid(payload);
      break;
    // ... other event types
  }
  
  // Return success response
  res.status(200).send('success');
});

• Use the raw JSON body string for signature verification (before parsing)
• Use your API Key as the secret
• Signature algorithm is HMAC-SHA256 with Base64 encoding
• Always use crypto.timingSafeEqual() for signature comparison to prevent timing attacks
• You can combine both methods for defense in depth

• API Key Verification (Method 1): Simpler to implement, suitable for most use cases
• HMAC Signature Verification (Method 2): Provides stronger security, recommended for production systems handling sensitive data
• Both Methods: You can implement both checks for maximum security

​

Errors and retries

​

Testing Webhooks

1. Use Sandbox API: Point your integration to https://api-sandbox.unibee.top
2. Configure Webhook Endpoint:
   • Option A: Deploy your webhook endpoint to a public URL (e.g., a staging server or cloud function) - recommended for production testing
   • Option B: Use a local development tool (e.g., ngrok, localtunnel, or similar) to temporarily expose your local webhook endpoint to the internet
   • Ensure the URL remains stable during testing, as webhook events will be sent to the configured URL
3. Test Webhook Events: Trigger events in the Sandbox environment (e.g., create subscriptions, process payments)
4. Verify Webhook Deliveries: Monitor webhook deliveries in UniBee Admin Portal to ensure events are received correctly
   • Go to Configuration → Webhooks → Webhook Endpoints
   • Click on your webhook endpoint to see the list of events
   • Check the Request Body and Response to verify event processing
5. Test Verification Methods: Ensure both API key and HMAC signature verification work correctly in your testing environment

• Test all webhook events you’ve subscribed to
• Verify idempotency handling using the EventId header
• Test error scenarios (network failures, invalid responses)
• Monitor webhook logs to catch any issues early
• Use test cards for payment-related webhooks (see Testing Cards)

• Webhook endpoint uses HTTPS
• Webhook signature verification is implemented
• Idempotency is handled correctly (using EventId header)
• Error handling is robust
• Monitoring and alerting are set up for webhook failures
• All subscribed webhook events are tested