Subscription Management API

All endpoints accept and return JSON.

Create/Subscribe

Method/Path

POST {API_BASE_URL}/webhooks/subscribe

Body

{
  "merchant_id": "your_merchant_id",
  "url": "https://yourapp.com/webhooks/aerosync",
  "events": [
    "job.balance",
    "job.transaction",
    "job.identity"
  ],
  "secret_key": "optional-shared-secret"
}

Response (201)

{
  "webhook_id": "uuid",
  "merchant_id": "your_merchant_id",
  "url": "https://yourapp.com/webhooks/aerosync",
  "events": [
    "..."
  ],
  "status": "active",
  "created_at": "2025-01-01T00:00:00.000000"
}

List

Method/Path

POST {API_BASE_URL}/webhooks/list

Body

{
  "merchant_id": "your_merchant_id"
}

Response (200)

{
  "subscriptions": [
    {
      "webhook_id": "...",
      "url": "...",
      "events": [
        "..."
      ],
      "status": "active",
      "failure_count": 0,
      "last_success_at": null,
      "last_failure_at": null,
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "total_count": 1
}

Update (change URL/events/secret)

Method/Path:

PATCH {API_BASE_URL}/webhooks/{webhook_id}

Body

{
  "merchant_id": "your_merchant_id",
  "url": "https://yourapp.com/new-webhook-url", //optional
  "events": [
    "job.transaction",
    "..."
  ],//optional
  "secret_key": "new-secret"//optional
}

Response (200)

 {
      "webhook_id": "...",
      "merchant_id": "your_merchant_id",
      "url": "https://yourapp.com/new-webhook-url",
      "events": ["..."],
      "status": "active",
      "updated_at": "2025-01-01T00:00:00.000000",
      "message": "Webhook subscription updated successfully"
 }

Pause

Method/Path

POST {API_BASE_URL}/webhooks/{webhook_id}/pause

Body

{
  "merchant_id": "your_merchant_id",
  "reason": "maintenance"
}

Response (200)

{
  "message": "Webhook subscription paused successfully"
}

Unpause

Method/Path

POST {API_BASE_URL}/webhooks/{webhook_id}/unpause

Body

{
  "merchant_id": "your_merchant_id"
}

Response (200)

{
  "message": "Webhook subscription unpaused successfully"
}

Delete

Method/Path

DELETE {API_BASE_URL}/webhooks/{webhook_id}

Body

{
  "merchant_id": "your_merchant_id"
}

Response (200)

{
  "success": true,
  "message": "Webhook subscription deleted successfully"
}

Test Delivery

Method/Path

POST {API_BASE_URL}/webhooks/test

Body

{
  "merchant_id": "your_merchant_id",
  "webhook_id": "uuid",
  "event": "test.event",
  "data": {
    "message": "This is a test"
  }
}

Response (200)

{
  "webhook_id": "uuid",
  "event": "test.event",
  "delivery_attempts": [
    {
      "attempt_number": 1,
      "status": "success",
      "response_code": 200,
      "duration_ms": 123,
      "attempted_at": "..."
    }
  ],
  "success": true
}

Notes

We auto-pause a subscription after 5 consecutive failures (including test deliveries). You can manually unpause anytime.
INACTIVE subscriptions (deleted) cannot be updated.