Webhook Setup

Receive real-time notifications for order status changes, messages, and deliveries directly to your server.

How Webhooks Work

Server-to-Server Communication

Instead of constantly polling our API to check if your service order is completed or if an admin replied to your chat, you can provide us with a Webhook URL. Whenever an important event occurs, we will send an instantaneous HTTP POST request containing a JSON payload to your URL.

5-Second Timeout

Your server must respond with a 2xx status code within 5000ms, otherwise the request is marked as failed and dropped.

Secure Delivery Data

Credentials are never sent directly in the webhook payload. You must fetch the API when an order completes to retrieve sensitive data.

Event Payloads

All webhooks are sent as POST requests with Content-Type: application/json. Your endpoint should inspect the event key to determine how to process the payload.

Event: `order_chat_message`

Fired when an admin or customer sends a message or file attachment into the order's chat thread.

{
  "event": "order_chat_message",
  "orderId": "U35MFE9656S7",
  "senderType": "STAFF",
  "message": "We have checked the account. Please review the attached config.",
  "fileUrl": "https://hsmail.shop/uploads/config.txt",
  "timestamp": "2024-03-24T10:00:00.000Z"
}

Event: `order_status_changed`

Fired when an admin updates the status of your service order to PROCESSING or COMPLETED.

{
  "event": "order_status_changed",
  "orderId": "U35MFE9656S7",
  "status": "COMPLETED",
  "productName": "Netflix Premium 1 Month",
  "warrantyEndsAt": "2024-04-24T10:00:00.000Z",
  "timestamp": "2024-03-24T10:30:00.000Z"
}

Event: `order_delivered`

Fired when an admin executes a delivery. You should immediately make a GET /v1/order/:id request to retrieve the newly generated credentials in the deliveryData field.

{
  "event": "order_delivered",
  "orderId": "U35MFE9656S7",
  "status": "DELIVERED",
  "productName": "Netflix Premium 1 Month",
  "warrantyEndsAt": null,
  "timestamp": "2024-03-24T10:25:00.000Z"
}

Event: `order_reopened`

Fired when a completed order is reopened under warranty via your API request.

{
  "event": "order_reopened",
  "orderId": "U35MFE9656S7",
  "status": "COMPLETED",
  "isReopened": true,
  "warranty": {
      "warrantyEndsAt": "2024-04-24T10:00:00.000Z",
      "isActive": true
  },
  "productName": "Netflix Premium 1 Month",
  "timestamp": "2024-03-25T11:00:00.000Z"
}

Example Receiver (Express.js)

Here is a basic example of how you can configure a Node.js Express server to listen for our webhooks and process the events optimally.

const express = require('express');
const app = express();

// Parse JSON bodies
app.use(express.json());

app.post('/hsmail-webhook', (req, res) => {
    // 1. Instantly respond 200 OK to prevent timeouts!
    res.status(200).send('Received');

    // 2. Process payload asynchronously
    const payload = req.body;

    if (payload.event === 'order_status_changed' && payload.status === 'COMPLETED') {
        console.log(`Order ${payload.orderId} finished! Fetching delivery data...`);
        // TODO: Call GET /v1/order/:id using your API key
    } 
    else if (payload.event === 'order_chat_message') {
        console.log(`New msg on ${payload.orderId} from ${payload.senderType}: ${payload.message}`);
    }
});

app.listen(3000, () => console.log('Webhook server active on port 3000'));