What API capabilities are available for developers?

US Global Mail supports Webhooks to help you stay informed about key events in your account and automate workflows by integrating with your CRM, applications, or other systems. Available on Enterprise plan.

How to Use Webhooks?

Navigate to Webhooks (https://inbox.usglobalmail.com/app/settings/automations/webhooks)
1. Log in and go to Settings → Automations → Webhooks.
Webhook Secret
- A private key used to generate an HMAC signature for each webhook payload.
- The signature (USGM-Webhook-Signature header) allows you to verify that requests originate from US Global Mail and have not been altered.
- Store this secret securely and rotate it anytime via Reset Secret.
Add a Webhook Endpoint
1. Select an Event from the dropdown.
2. Enter your Endpoint URL.
3. Click Add.
Manage Your Webhooks
- Activate/Deactivate: Toggle delivery on or off.
- Test: Send a sample payload immediately.
- Delete: Remove the endpoint permanently.
API Management
1. For advanced use, manage webhooks via our API. Authenticate using your access token and follow the Swagger Docs.

Supported Events

Event Key	Description
`new-mail`	A new mail item has arrived
`shipment-update`	Shipment status has been updated
`scan-update`	A scan request has completed
`open-update`	An open request has completed

Sample Payloads

{
  "measurement": {
    "width": "9",
    "height": "0.01",
    "length": "4"
  },
  "id": 111111,
  "weight": "0.03",
  "mail_status": "INBOX",
  "mail_type": "LETTER",
  "image_url": "https://usgm-fe-media-prod.s3.us-east-1.amazonaws.com/sample_mail.jpg",
  "message": "New mail received."
}


{
  "id": "b3ba0f4f-9ae6-4256-8b70-cd5f404756a9",
  "auto_forward": "false",
  "destination_address": {
    "name": "Home Address",
    "address_line": "2204 18th Street NW",
    "address_line_2": "Apt 3B",
    "city": "Washington",
    "state": "District of Columbia",
    "postal_code": "20009",
    "country": "United States",
    "address_type": "residential",
    "tax_id": "123-45-6789",
    "phone_number": "+1-202-555-0143"
  },
  "service": "DHL Express Easy",
  "status": "PROCESSED",
  "tracking_data": "1234567890",
  "message": "Shipment request updated"
}


{
  "id": 111111,
  "uuid": "b3ba0f4f-9ae6-4256-8b70-cd5f404756a9",
  "mail_type": "LETTER",
  "scan_result_url": "https://usgm-fe-media-prod.s3.amazonaws.com/sample.pdf",
  "current_status": "COMPLETED",
  "message": "Your scan request has been completed!!"
}

{
  "id": 111111,
  "uuid": "b3ba0f4f-9ae6-4256-8b70-cd5f404756a9",
  "mail_type": "PACKAGE",
  "open_result_url": "https://usgm-fe-media-prod.s3.amazonaws.com/sample.pdf",
  "current_status": "COMPLETED",
  "message": "Your open request has been completed!!"
}

Every webhook request includes two headers:

USGM-Webhook-Signature
USGM-Webhook-Timestamp

Verify in Node.js:

const express = require("express");
const crypto = require("crypto");
const app = express();

const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET";

app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf;
  }
}));

app.post("/webhook", (req, res) => {
  const sig = req.get("USGM-Webhook-Signature");
  const ts = req.get("USGM-Webhook-Timestamp");
  if (!sig || !ts) return res.status(400).send("Missing headers");

  const data = `${ts}.${req.rawBody.toString()}`;
  const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(data).digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(400).send("Invalid signature");
  }

  console.log("Webhook payload:", req.body);
  res.sendStatus(200);
});

Always use HTTPS and validate signatures to secure your integration.

Additional Notes

No automatic retries for failed deliveries.
Up to 10 active webhooks per user.
Each webhook URL must be unique per event.

Zapier Integration

For no-code automation, see our Zapier guide:
Zapier Integration Guide

Need help? Email: [email protected]