Webhooks

Webhook Integration

Receive real-time notifications for orders, deliveries, and platform events.

Overview

Webhooks allow your server or external services to receive real-time HTTP POST notifications when events occur on WERM. This is useful for:

Triggering custom actions when a purchase is made
Syncing order data with external systems
Building Discord bots that announce purchases
Creating custom analytics dashboards
Integrating with other platforms

Setting Up Webhooks

Navigate to Webhook Settings

Go to Dashboard → Settings → Webhooks

Add Webhook URL

Enter your endpoint URL that will receive webhook payloads

Select Events

Choose which events should trigger webhook notifications

Save & Test

Save your webhook and use the test button to verify it works

Available Events

order.created

Triggered when a new order is placed successfully.

order.completed

Triggered when an order is fully delivered to the player.

order.refunded

Triggered when an order is refunded (full or partial).

delivery.pending

Triggered when delivery is queued (player offline).

delivery.completed

Triggered when commands are successfully executed in-game.

delivery.failed

Triggered when delivery fails after maximum retries.

Payload Structure

All webhooks are sent as HTTP POST requests with a JSON body:

{
  "event": "order.created",
  "timestamp": "2024-12-23T10:30:00.000Z",
  "data": {
    "order_id": "ord_abc123",
    "server_id": "srv_xyz789",
    "player": {
      "username": "Notch",
      "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
    },
    "products": [
      {
        "id": "prod_vip",
        "name": "VIP Rank",
        "quantity": 1,
        "price": 999
      }
    ],
    "total": 999,
    "currency": "USD",
    "status": "pending_delivery"
  }
}

Security

Signature Verification

All webhook requests include an HMAC signature in the X-WERM-Signature header. Verify this signature to ensure the request is from WERM.

// Node.js verification example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Request Headers

Header	Description
X-WERM-Signature	HMAC-SHA256 signature of the payload
X-WERM-Timestamp	Unix timestamp when the webhook was sent
X-WERM-Event	The event type (e.g., order.created)

Best Practices

Respond Quickly

Return a 2xx response within 5 seconds. Process the webhook asynchronously if you need more time.

Handle Duplicates

Webhooks may be sent more than once. Use the order_id to detect duplicates and make your processing idempotent.

Verify Signatures

Always verify the X-WERM-Signature header to ensure webhooks are authentic and haven't been tampered with.

Use HTTPS

Webhook endpoints must use HTTPS to ensure data is encrypted in transit.

Retry Policy

If your endpoint doesn't respond with a 2xx status code, WERM will retry the webhook:

1st retry: 1 minute after initial attempt
2nd retry: 5 minutes after 1st retry
3rd retry: 30 minutes after 2nd retry
4th retry: 2 hours after 3rd retry
Final retry: 24 hours after 4th retry