Platform Webhooks

What is the event model?

Each time a subscription, charge, or product plan changes in Recurring Payments, an event is sent to the URLs registered in Platform Webhooks for that tenant_key and event_key.

This is the tenant / partner channel: one integration endpoint per partner (B2B), not per merchant. Merchant-level delivery uses a separate channel (Merchant Webhooks); contact Geopagos if you need both.

For schemas, examples, and the full integration guide, see Webhooks — integration guide.

Recommendations

• Handle events assuming the model evolves; ignore unknown JSON properties.
• Implement idempotent consumers (subscription_id, charge_id, or plan_id + event_type).
• Expect at-least-once delivery; duplicates can occur on retries.
• Use event_type in the POST body to branch logic (always present).

Onboarding (summary)

1. Coordinate with Geopagos to register your technical tenant_key and listener URLs in Platform Webhooks. Recurring Payments does not create listeners on your behalf.
2. SRE configures mTLS from Platform Webhooks to your endpoint in production (certificates and routing). This is the standard tenant delivery path—not optional plain HTTPS set up only by the partner.
3. Ensure your tenant is enabled on the Recurring Payments side with a matching PlatformWebhooks.TenantKey (lowercase slug, e.g.).
4. Register one listener per event you need—up to nine for the full catalog (subscriptions, charges, and product plans).
5. Expose a handler that returns 2xx quickly on POST JSON.

See Integration steps for tenant_key rules and the event list.

General information

The available events are listed below with links to the schema and examples for each message.

Although each event has its own model, keep in mind when listening to events:

Field	Type	Description
event_type	string	Event identifier (e.g. subscription.created, charge.failed)

Platform Webhooks forwards only the business payload. The HTTP body is a JSON object with event_type and the event-specific fields (snake_case, UUIDs as strings). Optional fields are omitted when they have no value.

Available events

Identificator	Event	Description
subscription.created	Subscription created	Dispatched when a subscription becomes active or trial with a payment method
subscription.cancelled	Subscription cancelled	Dispatched on manual cancellation
subscription.paused	Subscription paused	Dispatched on manual pause
subscription.reactivated	Subscription reactivated	Dispatched on manual reactivation or recovery from past due after a successful charge
charge.successful	Charge successful	Dispatched when a recurring charge is approved
charge.failed	Charge failed	Dispatched when a recurring charge is rejected or fails
product_plan.created	Product plan created	Dispatched when a plan is created
product_plan.updated	Product plan updated	Dispatched when a plan is updated
product_plan.canceled	Product plan canceled	Dispatched when a plan is deactivated