Manage endpoints - Ionic Docs

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, 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.

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...",
  "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.

​Create an endpoint

​Filtering events

​List, retrieve, update

​Disable and delete

​Rotate the signing secret

Create an endpoint

Filtering events

List, retrieve, update

Disable and delete

Rotate the signing secret