Webhook Events

This documentation explains how webhook events are sent to providers when configured in the PilloTrack Dashboard.

Overview

When a provider configures their webhook URL in the dashboard, they will receive HTTP POST requests containing event data. All events are sent with HMAC-SHA256 signatures for security validation.

Event Types

1. Order Create (order.create)

Sent when a new order is created in the system.

Payload Structure:

{
  "event": "order.create",
  "id": "uuid-of-event",
  "timestamp": "2023-01-01T00:00:00Z",
  "source": "order_id",
  "data": {
    "id": "order_id",
    "order_status": "created"
  }
}

2. Order Update (order.update)

Sent when an order status is updated.

Payload Structure:

{
  "event": "order.update",
  "id": "uuid-of-event",
  "timestamp": "2023-01-01T00:00:00Z",
  "source": "order_id",
  "data": {
    "order_status": "shipped"
  }
}

3. OTP Create (otp.create)

Sent when a one-time password is generated for an order.

Payload Structure:

{
  "event": "otp.create",
  "id": "uuid-of-event",
  "timestamp": "2023-01-01T00:00:00Z",
  "source": "order_id",
  "data": {
    "code": "123456"
  }
}

Signature Validation

All webhook requests include an X-Track-Signature-256 header that contains an HMAC-SHA256 signature for security validation.

How to Validate

To validate the signature on your end:

1. Extract the request body
2. Get the App Key from your company's webhook configuration
3. Calculate the HMAC-SHA256 signature using the App key
4. Compare with the value in X-Track-Signature-256 header

Python Example:

import hmac
import hashlib
import json

def validate_signature(request_body, secret_key, signature_header):
    # Extract signature from header (remove 'sha256=' prefix)
    expected_signature = signature_header.replace('sha256=', '')
    
    # Calculate actual signature
    actual_signature = hmac.new(
        secret_key.encode('utf-8'),
        request_body,
        hashlib.sha256
    ).hexdigest()
    
    # Compare signatures (use constant-time comparison to prevent timing attacks)
    return hmac.compare_digest(actual_signature, expected_signature)

Webhook URL Configuration

Prividers can configure their webhook URLs in the dashboard:

1. Navigate to API & Webhook tab in settings
2. Set the URL where events should be sent
3. The system will automatically generate a secure key for signature validation

Security Considerations

• All webhooks are signed with HMAC-SHA256 using your company's unique App Key
• Events are sent over HTTPS
• Only the system administrator can regenerate App Keys

Event Delivery

• The system attempts delivery with retries for failed requests
• Successful deliveries are marked as processed in the database

Testing Webhooks

To test your webhook endpoint:

1. Configure your webhook URL in the API & Webhook tab in settings
2. Use the admin panel to trigger a test event
3. Verify that you receive the expected payload with valid signature
4. Ensure your endpoint returns HTTP 200 status for successful processing

Support

If you experience issues with webhooks, please contact support with:

• Your company name
• The webhook URL being used
• Error messages or logs from your endpoint
• Timestamps of failed events