Webhook Format

Our platform uses webhooks to send real-time updates about orders to your system. This document outlines the format of these webhooks, how to receive them reliably, and best practices for implementation.

Payload Format

Webhooks are sent as POST requests with the payload in JSON format. Here's the structure of the payload:

{
  "event": Int,
  "order": {
    "id": String,
    "friendly_id": String,
    "external_id": String or NULL,
    "pack_requested": Boolean,
    "payment_type": String,
    "source": String,
    "name": String,
    "phone_number": String,
    "email": String,
    "bank_account_number": String,
    "bank_account_sort_code": String,
    "paypal_email": String,
    "line_1": String,
    "line_2": String or NULL,
    "line_3": String or NULL,
    "postcode": String,
    "town": String,
    "county": String,
    "country": String,
    "postage_type": Int,
    "postage_provider": Int
  },
  "devices": [
      {
        "device": String,
        "network": String,
        "condition": String,
        "price": Float,
        "product": String,
        "condition": String,
        "variation": String,
        "external_id": String,
        "manufacturer": String
      }
  ]
}

Event Types, Payment Types, Postage Types, and Postage Providers

Below are a few of the possible values for the event, payment_type, postage_type, and postage_provider fields:

Receiving Webhooks Reliably

To ensure you receive and process webhooks reliably, consider the following best practices:

1. Acknowledge Receipt Quickly

Respond to the webhook request with a 200 OK status code as soon as you've received it. Process the webhook asynchronously to avoid timeout issues.

2. Implement Idempotency

Design your webhook handler to be idempotent. This means that receiving the same webhook multiple times should not result in duplicate actions in your system.

3. Validate the Webhook

Implement security measures to ensure the webhook is genuine:

• Use HTTPS for all webhook endpoints
• Validate the webhook signature (if provided)
• Whitelist our IP addresses (contact us for the current list)

4. Handle Retries

We implement a retry mechanism for failed webhook deliveries:

• Retries occur at increasing intervals (e.g., 5 minutes, 30 minutes, 2 hours, 6 hours, 24 hours)
• After 5 failed attempts, the webhook is marked as permanently failed
• You can request a manual retry for permanently failed webhooks

5. Monitor Webhook Health

Implement logging and monitoring for your webhook endpoint to quickly identify and resolve any issues.

SSL Certificates

We require all webhook endpoints to use valid SSL certificates:

• TLS 1.3 or higher is required
• Certificates must be trusted by major certificate authorities
• We use the Mozilla Certificate Bundle to validate certificates
• Test your SSL configuration using SSL Labs (opens in a new tab)

Best Practices for Webhook Processing

1. Queue Processing: Use a queue system to process webhooks asynchronously.
2. Logging: Implement comprehensive logging for debugging and auditing.
3. Error Handling: Gracefully handle and log any errors during webhook processing.
4. Timeout Handling: Ensure your webhook handler completes processing within a reasonable time frame (we timeout after 30 seconds).
5. Testing: Use our webhook testing tools to verify your implementation.

Need Help?

If you encounter any issues with webhook delivery or processing, please contact our support team. We're here to ensure a smooth integration with our platform.