Manage endpoints

A webhook endpoint is a URL plus the set of event types it should receive. Manage endpoints from the API with a secret key, or from the dashboard. Endpoints are scoped to one mode: a sk_v1_test_… key manages test-mode endpoints, and a live key manages live ones. On Node, npm install @ionicfi/sdk gives you typed calls for every request below; the server SDK guide has details. Each example also shows raw curl. Every write on this API (create, update, delete, rotate) requires an Idempotency-Key header; the SDK types it as a required field on those calls.

Platform webhooks for connected accounts

Open Webhooks in the dashboard. Choose This account for events belonging to the business whose workspace you opened, or Connected accounts for events from merchants connected to your platform. Each view has separate endpoints, signing secrets, and embedded delivery activity. The test/live toggle applies to both. The Connected accounts choice appears only when your current Program and dashboard permissions allow it. For a server integration:

Ask Ionic to enable connect_webhooks for your active Platform Program and approve webhook_endpoints:read and webhook_endpoints:write in its permission ceiling. The target environment and delegated API capability must also be enabled.
In Connect → API keys, select the Webhook management preset and create a restricted Platform key. Save the credential securely. This preset manages endpoints; it does not grant access to connected-account resources.
Use that Platform credential with the endpoint APIs below. Omit Ionic-Account: the endpoint belongs to your Platform and receives its eligible connected-merchant stream. A direct merchant API key cannot select this stream.
Subscribe to the events you need. Delivery also requires an active Connection with the matching resource’s read permission—for example, payments:read for payment events. Minimal account.created / account.updated lifecycle status requires an active Connection and Program, without a profile-read grant. Registering an endpoint does not grant resource permissions.
Verify the webhook signature before using the payload. Its top-level account is the receiving connected account’s Ionic mer_… ID. Match it to the merchant ID your application stored on the order, together with the PaymentIntent ID and mode. Keep processing and deduplication scoped to that merchant.

Program status, environment, capability, and the current permission ceiling are checked on every management request. Existing keys are not automatically widened when Ionic approves additional permissions. The embedded Activity view is inspection-only: delivery attempts and payloads, without secret reveal, secret rotation, endpoint changes, or replay/example sends. Use the native Endpoints tab for configuration and secret rotation. Automated delivery retries still operate; this view does not grant unrestricted manual replay.

Create an endpoint

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const endpoint = await ionic.webhookEndpoints.create({
  "Idempotency-Key": "register-fulfillment-endpoint",
  url: "https://example.com/webhooks/ionic",
  event_types: ["payment_intent.succeeded", "refund.succeeded"],
  description: "Order fulfillment",
});

console.log(endpoint.secret); // whsec_..., shown only in this response

curl https://api.ionicfi.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: register-fulfillment-endpoint" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/ionic",
    "event_types": ["payment_intent.succeeded", "refund.succeeded"],
    "description": "Order fulfillment"
  }'

Field	Required	Description
`url`	yes	HTTPS URL Ionic delivers to.
`event_types`	yes	Which events to receive. See filtering for wildcards.
`description`	no	A label for your own reference.
`api_version`	no	Snapshot version to pin. Defaults to the current version (`2026-05-01`).

The response is the endpoint object. The secret is present only in this create response and in a rotate response — store it now; it’s never returned again.

{
  "id": "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
  "object": "webhook_endpoint",
  "merchant_id": "mer_8Qd2...",
  "scope": "account",
  "livemode": false,
  "url": "https://example.com/webhooks/ionic",
  "description": "Order fulfillment",
  "event_types": ["payment_intent.succeeded", "refund.succeeded"],
  "api_version": "2026-05-01",
  "status": "active",
  "disabled": false,
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZ...",
  "created_at": 1746122645,
  "updated_at": 1746122645
}

secret appears once. If you lose it, you can’t read it back — rotate to get a new one. Ionic stores only what’s needed to verify; it never persists the raw whsec_ value.

Filtering events

event_types accepts three forms, which you can mix in one array:

Form	Example	Matches
Exact type	`"payment_intent.succeeded"`	Just that event.
Resource wildcard	`"checkout.session.*"`	Every event for that resource.
All events	`"*"`	Every event type.

Subscribe only to what you handle — it keeps your endpoint’s traffic and your logs focused. You can change the set any time with an update.

List, retrieve, update

// List (most recent first). The secret is never included here.
const endpoints = await ionic.webhookEndpoints.list();

// Retrieve one
const endpoint = await ionic.webhookEndpoints.retrieve({
  id: "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
});

# List (most recent first). The secret is never included here.
curl https://api.ionicfi.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_v1_test_..."

# Retrieve one
curl https://api.ionicfi.com/v1/webhook_endpoints/whe_0J8kP2mNq7rVxYzAbCdEfGhI \
  -H "Authorization: Bearer sk_v1_test_..."

List responses wrap the array in data:

{ "data": [ { "id": "whe_0J8k...", "object": "webhook_endpoint", "...": "..." } ] }

Update with POST or PATCH and only the fields you’re changing — url, description, or event_types:

const updated = await ionic.webhookEndpoints.patch({
  id: "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
  "Idempotency-Key": "subscribe-all-events",
  body: { event_types: ["*"] },
});

curl -X PATCH https://api.ionicfi.com/v1/webhook_endpoints/whe_0J8kP2mNq7rVxYzAbCdEfGhI \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: subscribe-all-events" \
  -H "Content-Type: application/json" \
  -d '{ "event_types": ["*"] }'

Disable and delete

Disable an endpoint to stop deliveries while keeping it (and its secret) intact — useful during maintenance:

await ionic.webhookEndpoints.patch({
  id: "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
  "Idempotency-Key": "pause-fulfillment-endpoint",
  body: { disabled: true },
});

curl -X PATCH https://api.ionicfi.com/v1/webhook_endpoints/whe_0J8kP2mNq7rVxYzAbCdEfGhI \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: pause-fulfillment-endpoint" \
  -H "Content-Type: application/json" \
  -d '{ "disabled": true }'

disabled and status are two views of the same flag — {"disabled": true} is equivalent to {"status": "disabled"}, and status is only ever active or disabled. Re-enable with {"disabled": false}. Delete removes the endpoint permanently:

await ionic.webhookEndpoints.delete({
  id: "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
  "Idempotency-Key": "remove-fulfillment-endpoint",
});

curl -X DELETE https://api.ionicfi.com/v1/webhook_endpoints/whe_0J8kP2mNq7rVxYzAbCdEfGhI \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: remove-fulfillment-endpoint"

Rotate the signing secret

Rotating issues a new secret and returns it once. The previous secret keeps verifying for a brief overlap window, so deliveries already in flight (or signed just before the rotation) still pass — which is why a delivery’s webhook-signature header can carry more than one signature.

const rotated = await ionic.webhookEndpoints.rotateSecret({
  id: "whe_0J8kP2mNq7rVxYzAbCdEfGhI",
  "Idempotency-Key": "rotate-fulfillment-secret",
});

console.log(rotated.secret); // the new whsec_, returned once

curl -X POST https://api.ionicfi.com/v1/webhook_endpoints/whe_0J8kP2mNq7rVxYzAbCdEfGhI/rotate_secret \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: rotate-fulfillment-secret"

Roll out a rotation safely:

Rotate

Call rotate_secret and capture the new whsec_ from the response.

Accept both

Deploy your handler to verify against the new secret while still accepting the old one during the overlap.

Retire the old

Once the window has passed and all deliveries verify with the new secret, drop the old one.

What’s next

Browse the event catalog

Choose the event types to subscribe to.

Verify signatures

Check each delivery against the endpoint’s signing secret.

Set up platform webhooks

Receive events from connected accounts on a Platform endpoint.

SDKs

Webhooks

Resources

Platform webhooks for connected accounts

Create an endpoint

Filtering events

List, retrieve, update

Disable and delete

Rotate the signing secret

What’s next

Browse the event catalog

Verify signatures

Set up platform webhooks

​Platform webhooks for connected accounts

​Create an endpoint

​Filtering events

​List, retrieve, update

​Disable and delete

​Rotate the signing secret

​What’s next

Browse the event catalog

Verify signatures

Set up platform webhooks

Platform webhooks for connected accounts

Create an endpoint

Filtering events

List, retrieve, update

Disable and delete

Rotate the signing secret

What’s next