Skip to main content

Configuring Webhooks

This guide walks you through setting up and managing webhook configurations in your Wing account.

Creating a Webhook Configuration​

To receive webhook events, you need to register your webhook URL with Wing. This is done through the Create Webhook Configuration API endpoint.

Prerequisites​

  • A publicly accessible HTTPS URL on your server
  • Your URL should be ready to handle incoming POST requests

Basic Setup​

Use the Create Webhook Configuration endpoint:

curl -X POST https://api.wing.eu/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks",
    "events": ["order.created", "order.updated"],
    "name": "My Webhook"
  }'

Response​

{
  "id": "webhook_123456",
  "url": "https://your-domain.com/webhooks",
  "name": "My Webhook",
  "events": ["order.created", "order.updated"],
  "createdAt": "2024-02-18T10:30:00Z",
  "active": true
}

Managing Webhook Configurations​

List All Webhooks​

Retrieve all webhook configurations:

curl -X GET https://api.wing.eu/webhooks \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get Specific Webhook​

Retrieve a specific webhook configuration by ID:

curl -X GET https://api.wing.eu/webhooks/webhook_123456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Webhook​

Modify an existing webhook configuration:

curl -X PUT https://api.wing.eu/webhooks/webhook_123456 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/new-webhooks",
    "events": ["order.created", "order.updated", "fulfillment.shipped"]
  }'

Delete Webhook​

Remove a webhook configuration:

curl -X DELETE https://api.wing.eu/webhooks/webhook_123456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Webhook URL Requirements​

Your webhook endpoint should:

  1. Accept POST Requests

    • Content-Type: application/json
    • Body contains event data

  2. Return Success Response

    • Any 2xx status code (200, 201, 202, etc.)
    • Response is not required to have any specific content

  3. Be Publicly Accessible

    • HTTPS only (TLS/SSL required)
    • Must be reachable from the internet

  4. Handle Timeouts

    • Requests will timeout after 30 seconds
    • Implement retries server-side if needed

  5. Process Quickly

    • Don't perform long-running operations
    • Queue heavy tasks and process asynchronously

Verifying Webhook Requests​

All webhook requests include a signature header for verification:

X-Wing-Signature: v1=<hex_encoded_hmac_sha256>

Always verify the signature matches before processing the event. See Best Practices for implementation details.

Testing Your Webhook​

Local Testing with ngrok​

Use ngrok to expose your local server to the internet for testing:

# Terminal 1: Start your local server
npm start

# Terminal 2: Expose to internet
ngrok http 3000

# Use the ngrok URL as your webhook URL
# https://abc123.ngrok.io/webhooks

Manual Testing​

Trigger a test event through your dashboard or use the API to create test events.

Common Issues​

Webhook Not Being Called​

  1. Verify the URL is correct and publicly accessible
  2. Check that events are subscribed to the webhook
  3. Review server logs for any errors
  4. Ensure your firewall allows incoming requests

Signature Verification Failing​

  1. Verify you're using the correct signing secret
  2. Check the signature header format
  3. Ensure you're using the raw request body (not parsed JSON)

Timeouts​

  1. Respond quickly (< 5 seconds ideally)
  2. Process events asynchronously
  3. Return 202 Accepted if queuing for processing