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
3. You’ll privately receive a webhook_secret value that will be used for webhook authentication
4. This key will be sent to your API in the Authorization header as Bearer <webhook_secret> in each invocation of your webhook

​

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 Authorization header
• Handle duplicate events gracefully (use orderId for idempotency)

​

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

​

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',
    orderId: data.orderId,
    orderStatus: data.orderStatus
  });
});

​

Payload Structure

​

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 orderId 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