Webhooks

​

Overview

Webhooks allow your application to receive real-time notifications when events occur in Phoenix. When an order is created or its status changes, Phoenix can automatically send an HTTP POST request to your specified webhook endpoints.

​

Getting Started

​

1. Obtain Webhook API Key

Before setting up webhooks, you need to obtain a webhook API key from Phoenix:

1. Contact our support team at main@phoenix.market
2. Request webhook access for your integration

​

2. Define Your Webhook Endpoints

Your webhook endpoints should:

• Accept POST requests
• Return a 200 status code to acknowledge receipt
• Process the webhook payload within 30 seconds
• Validate the HMAC signature in the X-Webhook-Signature header
• Handle duplicate events gracefully (use id for idempotency)

​

HMAC Signature

Phoenix provides HMAC signatures to help you verify the authenticity of webhook requests. The signature is calculated using your client_secret and the payload of the request, allowing you to validate that the webhook came from Phoenix.

The signature is sent in the X-Webhook-Signature header.

The signature’s timestamp is sent in the X-Webhook-Timestamp header.

The signature is calculated using the HMAC-SHA256 algorithm.

​

Signature Verification Example

Here’s how to verify the webhook signature in your endpoint:

const crypto = require('crypto');

// In your webhook endpoint
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature']; // Or your custom header
  const timestamp  = req.headers['x-webhook-timestamp'];
  const rawBody = req.body; // Buffer, not parsed JSON!


const endpointSecret = 'Your-clientsecret-key'

  // Create the signed payload string
  const signedPayload = `${timestamp}.${JSON.stringify(rawBody)}`;

  // Compute the HMAC
  const expectedSignature = crypto
    .createHmac('sha256', endpointSecret)
    .update(signedPayload)
    .digest('hex');

    console.log(expectedSignature);
    console.log(signature);

  // Compare signatures (use timingSafeEqual in production)
  if (crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  )) {
    // Signature is valid, process the event
    console.log('Webhook verified!');
    res.status(200).send('Webhook verified!');
  } else {
    console.log('Invalid signature');
    // Invalid signature
    res.status(400).send('Invalid signature');
  }
});

​

3. Share Your Webhook Endpoint URLs

Once you’ve defined your webhook endpoints, you need to share the exact URLs with Phoenix:

1. Determine the full URL path where you want to receive webhooks (e.g., https://yourdomain.com/webhooks/phoenix-status-updates)
2. Contact our support team at main@phoenix.market with your webhook endpoint URL
3. Phoenix will configure the system to send webhook events to your specified URL

​

Webhook Events

Each webhook event contains a unique id field for deduplication. Implement idempotency using this id as Phoenix may retry events if your endpoint doesn’t return a 200 status code or if the request fails.

Current events:

• payment_link_created
• payment_link_status_updated
• order_created
• order_status_updated

​

Event Payload Structure

This structure may change over time, so do stay up to date with the docs.

{
  "event": "",
  "id": "xxx",
  "timestamp": "1970-01-01T00:00:00.001Z",
  "data": {
    "paymentLink" || "order": {
      "id": "xxx"
    }
  }
}

​

Querying Orders

You can query order details at any time using the Phoenix API. This is useful for getting the complete order information or checking the current status.

​

Endpoint

GET https://prod-phoenix-api-kwr2.encr.app/orders/:orderId

​

Example Request

const orderId = "tpT9KpKVyHU1P24RjZcW1o";
const response = await fetch(`https://prod-phoenix-api-kwr2.encr.app/orders/${orderId}`);
const orderData = await response.json();

​

Example Response

​

Order Status Update Webhook

​

Endpoint Configuration

Endpoint: /phoenix-order-status-updated Event Type: order.status.change Triggered: When an order’s status changes

​

Common Status Values

• fulfilled - Order has been completed successfully
• expired - Order expired before completion
• pending - Order is awaiting processing

​

Implementation Example

app.post('/phoenix-order-status-updated', (req, res) => {
  const { event, id, timestamp, data } = req.body;
  const { order, orderId, orderStatus } = data;
  
  // Validate required fields
  if (!event || !data || !data.orderId || !data.orderStatus) {
    return res.status(400).json({
      error: 'Missing required fields',
      required: ['event', 'data.orderId', 'data.orderStatus']
    });
  }
  
  // Validate authorization header
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({
      error: 'Missing or invalid authorization header'
    });
  }
  
  // Process the status update
  console.log(`Order ${data.orderId} status changed to: ${data.orderStatus}`);
  // Add your business logic here
  
  res.json({
    success: true,
    message: 'Order status webhook received',
    external_partner_id: "your-internal-order-123" // Optional: your own order ID
  });
});

​

Payload Structure

​

Webhook Response

Your webhook endpoint should return a JSON response with a 200 status code. You can optionally include an external_partner_id field to associate your own order ID with the Phoenix order:

// Basic response
res.json({
  success: true,
  message: 'Order status webhook received'
});

// Response with optional external partner ID
res.json({
  success: true,
  message: 'Order status webhook received',
  external_partner_id: "your-internal-order-123" // Optional: your own order ID
});

Optional Response Field:

• external_partner_id (string): Your internal order ID or reference that you want to associate with the Phoenix order. This helps you link Phoenix orders to your own system’s order tracking.

​

Authentication

Phoenix uses Bearer token authentication for webhooks:

• Header: Authorization: Bearer <webhook_secret>
• Webhook Secret: Provided by Phoenix support team
• Validation: Always verify the authorization header exists and contains a valid Bearer token

​

Best Practices

1. Validate Authentication: Always check the Authorization header
2. Validate Required Fields: Ensure all required fields are present
3. Implement Idempotency: Use id to handle duplicate events
4. Respond Quickly: Process webhooks within 30 seconds
5. Log Events: Keep logs for debugging and monitoring
6. Use HTTPS: Only accept webhooks over secure HTTPS connections
7. Handle Errors Gracefully: Return appropriate HTTP status codes

​

Support

For webhook-related questions or to request webhook access:

• Email: main@phoenix.market