Managing webhook subscriptions via the API

In addition to the web app control panel, you can create and manage webhook subscriptions programmatically through the public API using your API key.

📘

Authentication

All endpoints below require your API key. Add the token as the Authorization header value directly, with no Bearer prefix (the same way as the rest of the public API — see Starting with the API). For example: Authorization: <your-token>.

❗️

Supported events

The public API supports invoice_status (event ID 6), payment_status_changed (event ID 1), card_charge_status_changed (event ID 7), and card_charge_refund_status_changed (event ID 8). Check the events endpoint in your environment for availability. The selectedEvents field accepts a nonempty array of supported IDs; including an unsupported ID rejects the request with HTTP 400 rather than silently removing that ID.

List available events

Returns the webhook events you can subscribe to via the public API.

GET /api/v1/webhooks/events

Example response

{
  "events": [
    {
      "id": 6,
      "name": "invoice_status",
      "description": "status of the invoice and details of the invoice"
    },
    {
      "id": 1,
      "name": "payment_status_changed",
      "description": "status changes for payments, including direct payments"
    },
    {
      "id": 7,
      "name": "card_charge_status_changed",
      "description": "Card charge settlement, completion, failure and refund-derived status, with an itemized receipt"
    },
    {
      "id": 8,
      "name": "card_charge_refund_status_changed",
      "description": "Card refund processing, completion or failure, with the original receipt and confirmed returned amounts"
    }
  ]
}

Create a webhook subscription

POST /api/v1/webhooks/subscriptions

Request body

Example request

{
  "url": "https://your-app.com/webhooks/snaprefund",
  "secret": "your-secret-key",
  "selectedEvents": [6],
  "isActive": true
}

Example response

{
  "id": 1,
  "url": "https://your-app.com/webhooks/snaprefund",
  "isSecretExists": true,
  "isActive": true,
  "selectedEvents": [6]
}

Card charge and refund subscription

For card charge and refund updates, create an active subscription with both card events:

{
  "url": "https://your-app.com/webhooks/snaprefund",
  "secret": "your-secret-key",
  "selectedEvents": [7, 8],
  "isActive": true
}

Use an HTTPS receiver you control and configure it before creating the charge you want to observe. Validate the signature and see the card event examples for the payloads. Successful GET polling is not evidence of webhook delivery because the card-charge GET also refreshes state from the processor.

List your webhook subscriptions

GET /api/v1/webhooks/subscriptions

Returns a paginated list of the webhook subscriptions belonging to your account.

Get a webhook subscription by ID

GET /api/v1/webhooks/subscriptions/{id}

Update a webhook subscription

PUT /api/v1/webhooks/subscriptions/{id}

Accepts the same body as create. Use this to change the url, rotate the secret, toggle isActive, or update selectedEvents.

Delete a webhook subscription

DELETE /api/v1/webhooks/subscriptions/{id}

Example response

{
  "message": "Webhook subscription deleted successfully",
  "deletedSubscription": {
    "id": 1,
    "url": "https://your-app.com/webhooks/snaprefund"
  }
}