Skip to main content
A platform webhook endpoint receives events from every connected account whose connection allows it. Each event names the merchant it belongs to, so one endpoint can keep your records current for all of the businesses on your platform. Onboarding events for your own Account Links and connections arrive on your platform’s own endpoint. Delivery, signatures, retries, and the event envelope work as they do for any webhook endpoint.

​
Set up the endpoint

  1. Ask Ionic to enable connect_webhooks for your Platform Program and approve webhook_endpoints:read and webhook_endpoints:write in its permission ceiling.
  2. In Connect → API keys, create a restricted platform key with the Webhook management preset. It manages endpoints only and grants no access to merchants’ resources.
  3. Create the endpoint with that key and no Ionic-Account header. The endpoint belongs to your platform.
To manage the same endpoints in the dashboard, switch to the Connect workspace and open Webhooks. Each test or live endpoint has its own signing secret. See Platform webhooks for connected accounts.

​
Events your platform receives

Registering an endpoint grants no resource access. A merchant’s event is delivered when that merchant’s connection is active and grants the matching read permission, and your Platform Program allows that permission for Connect webhooks. See each type’s payload in the event catalog.

​
Onboarding and connection events

These events require the Connect lifecycle release in your environment and Connect webhooks on your Platform Program. Subscribe to your platform’s own events and connected accounts’ events separately; each endpoint has its own signing secret. See Hosted Connect lifecycle.

​
Match each event to a merchant

  1. Verify the signature before reading the payload.
  2. Read the top-level account field. It is the connected account’s mer_… ID.
  3. Match the merchant, the object ID, and the mode to the record your application stored, such as the order that holds the PaymentIntent ID.
  4. Deduplicate on the event id, and keep processing scoped to that merchant.
A verified signature proves the delivery came from Ionic. Matching the merchant, object ID, and mode ties the event to your record.

​
What’s next

Go live

Recreate your live configuration and verify each flow with real transactions.

Manage endpoints

Create, update, and rotate webhook endpoints.

Handle duplicates and retries

Process duplicate and out-of-order deliveries safely.