Webhooks

What Are Webhooks?

Webhooks allow Arcliance to push real-time notifications to your systems when events occur. Instead of polling our API, your server receives HTTP POST requests whenever something important happens.

Available Events

Setting Up Webhooks

1. Navigate to Integrations

   Go to Administration > Integrations > Webhooks

2. Add Webhook Endpoint

   Click Add Webhook and enter your endpoint URL.

3. Select Events

   Choose which events should trigger notifications to this endpoint.

4. Copy Signing Secret

   Save the signing secret for verifying webhook authenticity.

5. Test Webhook

   Click Send Test to verify your endpoint receives events.

Webhook Payload

All webhooks include a standard payload structure:

{
  "id": "evt_abc123",
  "type": "transaction.approved",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "transactionId": "tx_xyz789",
    "status": "APPROVED",
    "approvedBy": "user@company.com",
    "approvedAt": "2024-01-15T10:30:00Z"
  }
}

Verifying Webhooks

Verify that webhooks come from Arcliance by checking the signature:

// Node.js example
const crypto = require('crypto');

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

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

// Check the X-Arcliance-Signature header
const isValid = verifyWebhook(
  req.body,
  req.headers['x-arcliance-signature'],
  process.env.WEBHOOK_SECRET
);

Best Practices

• Always verify signatures - Don't trust unverified requests
• Respond quickly - Return 200 within 30 seconds
• Handle duplicates - Use event IDs for idempotency
• Process asynchronously - Queue events for background processing
• Monitor failures - Set up alerts for delivery failures

Retry Policy

If your endpoint returns an error or doesn't respond, we retry:

• 1st retry: 1 minute after initial failure
• 2nd retry: 5 minutes after
• 3rd retry: 30 minutes after
• 4th retry: 2 hours after
• 5th retry: 24 hours after

After 5 failed attempts, the webhook is disabled and you'll be notified.