Aerosync Webhooks

Integration Guide

This guide explains how to subscribe to Aerosync webhooks, verify requests, and handle events in your application. It covers endpoints for managing subscriptions and the event payloads you will receive.

Notes

• Delivery model: at-least-once
• Transport: HTTPS POST with JSON body
• Security: optional HMAC-SHA256 signature header when you set a secret_key
• Retries: up to 3 attempts with exponential backoff on non-2xx or timeout
• Auto-pause: after 5 consecutive delivery failures; you can unpause via API

Base URL

• Sandbox: https://api.sandbox-sync.aero.inc
• Production: https://api.sync.aero.inc

Note: In examples below, replace {API_BASE_URL} with the appropriate base URL.

Quick Start

1. Expose a public HTTPS endpoint in your system that accepts POST requests with JSON
2. (Recommended) Choose and store a secret key you will use to verify signatures
3. Create a webhook subscription via our API (see Subscribe endpoint)
4. Verify delivery with the Test endpoint
5. Start receiving real-time events

Authentication

All webhook subscription management API requests require authentication:

Required Headers:

• Authorization: Bearer {JWT_TOKEN} - Your JWT authentication token
• x-api-key: {YOUR_API_KEY} - Your API key for merchant identification Example request:

curl -X POST {API_BASE_URL}/webhooks/subscribe \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/aerosync",
    "events": ["job.balance", "job.transaction"],
    "secret_key": "optional-shared-secret"
  }'

Note: The webhook deliveries sent to your endpoint do NOT require these headers. These authentication headers are only needed when you call our API to manage subscriptions (subscribe, list, update, pause, unpause, delete, test).