Skip to main content

What are Webhooks?

Webhooks are a fundamental concept in modern API design. They provide a way for your application to be notified in real-time when events occur, rather than having to continuously check for updates.

The Basics​

Traditional Polling​

Without webhooks, you might need to regularly query our API:

Every 30 seconds: GET /api/orders
→ Check if anything new happened
→ Process any changes

This approach is inefficient and can miss events that occur between polling intervals.

Event-Driven with Webhooks​

With webhooks, you register a URL and we notify you:

Event occurs in Wing system
→ POST request sent to your webhook URL
→ Your system processes the event
→ You send a success response

Key Concepts​

Events​

An event is something that happens in your Wing system. Examples include:

  • An order is created
  • A fulfillment order status changes
  • A parcel is shipped

Webhook Endpoint​

Your webhook endpoint is an HTTP URL on your server that receives event notifications. It should:

  • Accept POST requests
  • Process the incoming JSON payload
  • Return a 2xx status code to confirm receipt
  • Handle timeouts gracefully

Event Delivery​

When an event occurs, we:

  1. Serialize the event data to JSON
  2. Send a POST request to your registered webhook URL
  3. Wait for a success response (2xx status code)
  4. Retry if the delivery fails (with exponential backoff)

Event Structure​

All webhook events follow a consistent structure:

{
  "id": "evt_1234567890",
  "type": "order.created",
  "timestamp": "2024-02-18T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Event Fields​

  • id - Unique identifier for this event
  • type - Event type (e.g., "order.created")
  • timestamp - When the event occurred (ISO 8601 format)
  • data - Event-specific information

Why Use Webhooks?​

Real-time Processing​

React to events as they happen, not minutes later

Resource Efficiency​

No polling overhead - we notify you when something changes

Better User Experience​

Provide instant feedback to your users instead of waiting for the next poll cycle

Cost Effective​

Reduce API calls and server resources used for polling

Reliability​

Built-in retry logic ensures you don't miss important events