Authentication
API
Webhooks
SDK

Subscription webhooks

Webhooks allow your server to automatically receive notifications about events in our system. Instead of periodically polling the API, you configure one endpoint and we send you an HTTP request for each important event.

To connect webhooks, you need:

  1. Create an HTTPS endpoint that accepts JSON requests.
  2. Send us the URL of this endpoint.
  3. Choose which events you want to receive.
  4. Accept and test webhook.

How it works in general

  1. An event occurs in our system (for example, a payment is created or its status has changed).
  2. We form a webhook notification in the form of an HTTP POST request with a JSON host.
  3. We send a request to your endpoint.
  4. Your server handles the request and responds with 2xx (usually 200) if it is successful.
Possible payment events
Reason
Event
Action
Outcome
To obtain information about the selected event.
check
API
The merchant receives a test webhook of the specified type (with the contract structure, mocked test data, etc.); as a result, they can test their own integration with the selected webhook type.
To obtain information about freezing a subscription.
subscription_manual_
freeze
freeze
The subscription status is changed to frozen; in a separate table, subscription_planned_unfreeze, the planned unfreeze date and the reason for freezing are recorded.
To obtain information about unfreezing a subscription.
subscription_manual_
unfreeze
subscription_scheduled_
unfreeze
unfreeze
unfreeze
The funds are debited from the customer’s account and transferred to the merchant’s account; a new subscription is created or the existing subscription is renewed.
The subscription status changes to active; the endDate may change.
To obtain information about subscription creation.
subscription_manual_
create
subscription_user_create
create
create
A subscription is created for the specified product with auto-charge disabled; it is not linked to a payment method, but it is linked to an existing buyer.
A subscription is created with the specified settings (product, auto-charge, payment method or without one). A charge_id is returned.
To obtain information about a chargeback on a subscription.
subscription_event_
chargeback
subscription_manual_
chargeback
suspend
suspend
The subscription status changes to suspended; auto-charge is turned off if it was enabled.
The subscription status changes to suspended; auto-charge is turned off if it was enabled.
To obtain information about a refund issued on a subscription.
subscription_event_refund
disable
The subscription status changes to disabled; auto-charge is turned off if it was enabled.
To obtain information about a void issued on a subscription.
subscription_event_void
disable
The subscription status changes to disabled; auto-charge is turned off if it was enabled.
To obtain information about a received refund / void on a subscription.
subscription_manual_
disable
disable
The subscription status changes to disabled; auto-charge is turned off if it was enabled.
To obtain information about expired or blocked subscriptions.
subscription_scheduled_
disable
disable
The subscription status changes to disabled; auto-charge is turned off if it was enabled.
To obtain information about changing the subscription status to blocked.
subscription_scheduled_
failed_capture
block
The subscription status is changed to blocked.
To obtain information about enabling auto-charge for a subscription.
subscription_scheduled_
failed_capture
auto_charge_on
Auto-charge on the subscription is enabled; the reason for enabling it is recorded by the support agent.
subscription_user_auto_
charge_on
auto_charge_on
Auto-charge on the subscription is enabled; a user comment with the reason for enabling auto-charge is recorded.
To obtain information about disabling auto-charge for a subscription.
subscription_manual_auto_charge_off
auto_charge_off
auto_charge_off
auto_charge_off
auto_charge_off
Auto-charge on the subscription is disabled; the reason for disabling it is recorded by the support agent.
Auto-charge on the subscription is disabled automatically.
Auto-charge on the subscription is disabled automatically.
Auto-charge on the subscription is disabled as a consequence of actions related to another subscription.
subscription_user_auto_
charge_off
auto_charge_off
Auto-charge on the subscription is disabled; a user comment with the reason for disabling auto-charge is recorded.
subscription_scheduled_
auto_charge_off
subscription_fraud_auto_
charge_off
subscription_system_
auto_charge_off
To obtain information about disabling auto-charge for a subscription.
subscription_manual_
upgrade
upgrade
renew
renew
renew
downgrade
downgrade
The subscription’s product, its price, and end date are changed; the auto-charge status and the subscription status may change.
The subscription’s product, its price, and end date are changed; the auto-charge status and the subscription status may change.
The subscription’s product, its price, and end date are changed; the auto-charge status, subscription status, and currency may change. A payment method may also be added or changed. A charge_id is returned.
The subscription’s product, price, end date, auto-charge status, and subscription status may change.
The subscription’s product, price, end date, auto-charge status, subscription status, and currency may change. A payment method may also be added or changed. A charge_id is returned.
The subscription’s end date is changed and its price, auto-charge status, and subscription status may change. A charge_id is returned.
subscription_user_
upgrade
upgrade
The subscription’s product, its price, and end date are changed; the auto-charge status, subscription status, and currency may change. A payment method may also be added or changed. A charge_id is returned.
subscription_manual_
downgrade
subscription_user_
downgrade
subscription_manual_
renew
subscription_user_renew
subscription_scheduled_
renew
To obtain information about changing the endDate for a subscription.
subscription_manual_end_date
end_date
The subscription’s endDate is changed (endDate = expired); the subscription status may change.
To obtain information about expired subscriptions.
subscription_scheduled_
expire
expire
The subscription status changes to expired.
To obtain information about linking a new token to a subscription.
subscription_manual_
token
tokenize
tokenize
The token on the subscription is updated.
The token on the subscription is updated.
subscription_rotation_
token
tokenize
The token on the subscription is updated.
subscription_scheduled_
token
Webhook-request format
Attribute
Type
Requirement
Description
Standard
type
string
mandatory
Type of event.
There will always be a subscription.
-
action
string
mandatory
Indicates event (subscription_user_renew, subscription_user_create, etc)
-
merchant
string
mandatory
Merchant's name
-
chargeId
string
optional
Transaction identifier
-
subscriptionData
object
mandatory
Contains subscription details
-
JSON
{
  "type": "subscription",
  "action": "subscription_manual_freeze",
  "merchant": "valid_merchant",
  "chargeId": "uuid",
  "subscriptionData": {
    "id": "uuid",
    "status": "frozen",
    "buyerId": "4dc68f5f-77bd-4d5f-b02b-2f518e757c19",
    "buyerEmail":"buyer_email@mail.co"
    "startDate": "2023-02-01 12:00:00",
    "endDate": "2023-03-21 12:00:00",
    "createdAt": "2023-02-01 12:00:00",
    "updatedAt": "2023-02-01 12:00:00",
    "isManual": true,
    "autochargeStatus": false,
    "product": {
      "code": "MSF1F",
      "name": "Product name",
      "nameByLocale": "Product name by locale",
      "productPrice": {
        "amount": 123.12,
        "currency": "USD"
      }
    }
  }
}
© 2025 BILLERIX LTD. All rights reserved