Webhook

Webhooks are a powerful way to receive real-time notifications from AlphaX.

They allow you to set up a callback URL that AlphaX will send HTTP POST requests to whenever certain events occur in your company.

How to Set Up a Webhook?

1. Log in to your AlphaX account (Director, HR, or Developer role).
2. Navigate to the “Developer” menu in the dashboard.
3. Click on “Webhooks” and then “Create new Webhook”.
4. Fill in the required fields:
   • Name: A descriptive name for your webhook.
   • Destination URL: The callback URL where you want to receive the notifications.
   • Events: Select the events you want to subscribe to.
5. Click “Submit” to save your settings.

Payload Structure

When an event occurs, AlphaX will send a POST request to your specified destination URL with a JSON payload containing the event details. The payload will have the following structure:

1
{
2
  "id": "unique_event_id",
3
  "type": "event.type",
4
  "payload": {
5
    // Event-specific data goes here
6
  },
7
  "createdAt": "2024-06-01T12:00:00Z"
8
}

Verifying Webhook Signatures

To ensure that the webhook requests you receive are genuinely from AlphaX, you can verify the signatures included in the request headers. Each webhook request will include a signature in the X-Signature header, which you can use to validate the authenticity of the request.

Use the raw request body and the secret key you set up when creating the webhook, and apply the HMAC SHA256 algorithm to generate a hash. Compare this hash with the signature provided in the X-Signature header to confirm that the request is legitimate.

Examples:

1
const crypto = require('crypto');
2
3
// 1. Get the raw request payload (buffer or string)
4
const rawPayload = '{"event": "user.created"}';
5
const secret = 'your_shared_secret';
6
const receivedSignature = '...'; // From headers
7
8
// 2. Generate HMAC SHA256
9
const hmac = crypto.createHmac('sha256', secret);
10
hmac.update(rawPayload);
11
const expectedSignature = hmac.digest('hex');
12
13
// 3. Verify using safe-time function
14
const isValid = crypto.timingSafeEqual(
15
    Buffer.from(receivedSignature),
16
    Buffer.from(expectedSignature)
17
);

Retry Mechanism

If your server fails to respond with a 2xx status code, AlphaX will automatically retry sending the webhook notification. The retry attempts will follow an exponential backoff strategy, with a maximum of 5 retries. This ensures that you have multiple chances to receive the notification in case of temporary issues with your server.

• First attempt: 10s after the initial failure
• Second attempt: 30s after the first retry
• Third attempt: 1 minute after the second retry
• Fourth attempt: 2 minutes after the third retry
• Fifth attempt: 5 minutes after the fourth retry

Available Events

• checkout_payment.succeeded
• checkout_payment.failed

checkout_payment.succeeded

This event is triggered when a payment for a checkout is successfully processed (for both SDK and Payment Link).

1
{
2
  "type": "checkout_payment.succeeded",
3
  "payload": {
4
    "transactionId": "01H2Z5Z8Z5Z5Z5Z5Z5Z5Z5Z5",
5
    "orderId": "Order_12345",
6
    "amount": 15.39,
7
    "currency": "USD",
8
    "paymentMethod": "card",
9
    "card": {
10
      "brand": "visa",
11
      "last4": "4242",
12
      "country": "US"
13
    },
14
    "capturedAt": "2024-06-01T12:00:00Z"
15
  }
16
}

checkout_payment.failed

This event is triggered when a payment for a checkout is failed to process (for both SDK and Payment Link).

1
{
2
  "type": "checkout_payment.failed",
3
  "payload": {
4
    "orderId": "Order_12345"
5
  }
6
}