Webhooks

What is the event model?

Each time a subscription, charge, or plan changes in Recurring Payments, the service emits a webhook event delivered through Platform Webhooks (tenant / partner channel).

For a product-oriented overview, see Platform Webhooks — tenant channel.

Recommendations

• Handle events assuming the model evolves: ignore unknown JSON properties.
• Implement idempotent consumers using entity IDs in the body (subscription_id, charge_id, or plan_id) together with event_type. The partner POST does not include internal envelope fields such as event_id or occurred_at.
• Expect at-least-once delivery; duplicates can occur on retries.
• Use event_type in the body to branch logic (it is always present in the partner POST).
• Do not parse failure_reason as JSON on charge.failed; it is a human-readable message (gateway details are stored internally only).

General information (partner POST body)

Platform Webhooks forwards only the data payload. Recurring Payments adds event_type inside that object when triggering delivery.

Field	Type	Description
event_type	string	Event key (e.g. subscription.created, charge.failed)
…	varies	Event-specific fields (see Events)

Correlation uses entity IDs inside the body (subscription_id, charge_id, plan_id, etc.).

Integration steps (Platform Webhooks)

1. Onboarding

Delivery requires two sides to be configured. Recurring Payments does not register listeners in Platform Webhooks; Geopagos coordinates partner onboarding with Platform Webhooks and SRE.

Step	Owner	What happens
1	Geopagos (Platform Webhooks / Mibo)	Register your tenant_key and create one listener per event_key you want, pointing to your webhook URL.
2	SRE	Configure mTLS between Platform Webhooks and your endpoint (client/server certificates, trust chain, ingress). This is how tenant delivery works in production—not plain HTTPS configured only by the partner.
3	Geopagos (Recurring Payments ops)	Enable the partner channel for your tenant in Recurring Payments (PlatformWebhooks.Enabled and PlatformWebhooks.TenantKey aligned with Platform).
4	Partner	Expose an HTTPS endpoint that accepts POST JSON and returns 2xx quickly; terminate mTLS as agreed with SRE.

tenant_key (technical slug)

Concept	Example	Notes
tenant_key in Platform Webhooks	geopagos, geo-pagos	Lowercase slug, no spaces. Used in listeners and in POST /v1/trigger.
PlatformWebhooks.TenantKey in Recurring Payments	Same as above	Must match Platform. This is what Recurring Payments sends when dispatching.
Tenant display name (Name in RP config)	Geopagos	For APM / business labels only. Do not use as tenant_key unless explicitly configured as fallback.

If PlatformWebhooks.TenantKey is not set in Recurring Payments, the service falls back to Name (which may contain spaces). Prefer setting an explicit slug at onboarding.

Listeners to register

Register one listener per (tenant_key, event_key). For the full v1 catalog, that is nine listeners per tenant:

• subscription.created, subscription.cancelled, subscription.paused, subscription.reactivated
• charge.successful, charge.failed
• product_plan.created, product_plan.updated, product_plan.canceled

You may register a subset if you do not need plan events yet; events without a listener are not delivered to your URL.

The curl below illustrates the Platform Webhooks API contract. In production, Geopagos runs this during onboarding—not the partner alone.

curl -X POST "https://platform-webhooks.<env>.geopagos.cloud/v1/listeners" \
  -H "Content-Type: application/json" \
  -d '{
    "hook_url": "https://your-platform.com/webhooks/recurring",
    "tenant_key": "your-tenant-slug",
    "event_key": "charge.successful"
  }'

Repeat for each event_key you need, using the same tenant_key everywhere.

2. Transport: mTLS (production)

In production, Platform Webhooks delivers tenant events to your URL over mutual TLS (mTLS). Certificate exchange, trust stores, and routing are set up by SRE together with your team during onboarding—not via self-service in this guide.

• Lower environments (DEV/QA) may use simpler HTTPS for smoke tests; production follows the mTLS process coordinated with Geopagos and SRE.
• Recurring Payments only triggers Platform Webhooks (POST /v1/trigger); it does not terminate mTLS to your endpoint.

3. Expose your webhook handler

• Accept POST with Content-Type: application/json.
• Respond with 2xx quickly; process asynchronously if needed.

4. Verify in a lower environment

Geopagos or your integration team can point a test listener to your staging URL, then trigger a subscription, charge, or plan change. Confirm the POST body matches the schema for that event_type.

Available events

Identifier	Event	Description
subscription.created	Subscription created	Subscription is active or in trial with a payment method
subscription.cancelled	Subscription cancelled	Manual cancellation
subscription.paused	Subscription paused	Manual pause
subscription.reactivated	Subscription reactivated	Manual reactivation or PastDue recovery after successful charge
charge.successful	Charge successful	Recurring charge approved
charge.failed	Charge failed	Charge rejected or failed after retries
product_plan.created	Product plan created	Plan created
product_plan.updated	Product plan updated	Plan updated
product_plan.canceled	Product plan canceled	Plan deactivated

Event groups and schemas

All events in a group share the same JSON Schema (see the schema viewer on each event page):

Group	Events
Subscriptions	subscription.created, subscription.cancelled, subscription.paused, subscription.reactivated
Charges	charge.successful, charge.failed
Product plans	product_plan.created, product_plan.updated, product_plan.canceled

Troubleshooting

Symptom	Likely cause
No events received	Listeners not registered in Platform Webhooks for your tenant_key / event_key, or partner channel not enabled for your tenant in Recurring Payments.
404 / listener not found on trigger	tenant_key mismatch between Platform listeners and PlatformWebhooks.TenantKey in Recurring Payments.
Only subscription/charge events, never plan events	Listeners missing for product_plan.* keys.