Webhooks

​

How it works

1. You register an endpoint: a public https URL on your backend, per environment (Sandbox, Live), subscribed to the event types you want (["*"] for all). From the dashboard (Webhooks tab) or with POST /v1/webhook-endpoints (ensc.webhookEndpoints.create).
2. ENSC delivers: one POST per event, JSON body, signed headers.
3. You verify, acknowledge, then process: check the signature over the raw body, answer 200, and do the work afterwards.
4. ENSC retries until your endpoint answers 2xx or the attempts run out, so you must handle duplicates.

​

Registering an endpoint

const endpoint = await ensc.webhookEndpoints.create({
  env: 'test',
  url: webhookUrl,          // a public https URL on your backend
  eventTypes: ['*'],
});

​

The delivery

POST /your/path HTTP/1.1
Content-Type: application/json
X-ENSC-Signature: ed25519=<base64url>
X-ENSC-Timestamp: 1789590000
X-ENSC-Webhook-Id: whk_01M2…
X-ENSC-Key-Id: ensc_2026_1
X-ENSC-Event-Type: conversion.succeeded
X-ENSC-Event-Id: ev_01M2…
X-ENSC-API-Version: 2026-09-15

{ "id": "ev_01M2…", "type": "conversion.succeeded", "apiVersion": "2026-09-15", "created": 1789590000, "data": { … } }

​

Verifying a delivery

ENSC-WH-V1\n<X-ENSC-Webhook-Id>\n<X-ENSC-Timestamp>\n<hex SHA-256 of the raw request body>

• Hash the raw bytes you received. Parsing the JSON and re-serialising it changes the bytes and the signature no longer matches.
• Refuse a delivery whose timestamp is more than 5 minutes from your clock; a retry always carries a fresh timestamp and signature.
• Compare in constant time, or use the SDK.

import { EnscClient } from '@ensc/sdk';

// ENSC's webhook keys as { [kid]: publicKey }. Load once and cache.
let enscKeys = await EnscClient.fetchPublicKeys();

export async function handleEnscWebhook(rawBody: string, headers: Headers): Promise<Response> {
  const kid = headers.get('X-ENSC-Key-Id');
  if (kid && !(kid in enscKeys)) enscKeys = await EnscClient.fetchPublicKeys(); // unknown kid: refetch
  let event;
  try {
    // the verifier picks the key named by X-ENSC-Key-Id
    event = EnscClient.constructEvent({ body: rawBody, headers, publicKey: enscKeys });
  } catch {
    return new Response('invalid signature', { status: 401 });
  }
  if (await alreadySeen(event.id)) return new Response(null, { status: 200 });
  await enqueue(event);                 // process after answering
  return new Response(null, { status: 200 });
}

​

Answering and processing

• Answer 2xx within 15 seconds. ENSC waits that long. Verify, record the event id, answer, then process. Do not call your bank, ENSC or a chain node before answering.
• Any other outcome is retried: a non-2xx answer, a redirect, a timeout or a connection failure. The retries come after 1 minute, 5 minutes, 15 minutes, 1 hour, 2 hours, 4 hours and 8 hours: 8 attempts in total over about 15 hours. Then the delivery is marked gave_up. Disabling the endpoint ends its retries.
• Delivery is at least once. A retry after a lost answer delivers the same event id again. Store the ids you have processed and skip duplicates.
• Order is not guaranteed. Two events for one conversion can arrive out of order or seconds apart. Act on the status the event carries, not on the sequence, and before releasing goods or money read the conversion back with GET /v1/conversions/{reference} (ensc.conversions.get(reference)).
• Credit on the final event: conversion.succeeded for crypto legs and fiat-issue, payout.succeeded for a fiat-redeem. Earlier events are progress, not money.
• Ignore fields you do not know. New fields can appear in a payload; write the handler so they do not break it.

​

Seeing what was delivered

​

Testing your receiver

1. Deploy the receiver to the URL you will register, on the same hosting as the rest of your backend.
2. Register that URL in Sandbox.
3. POST /v1/webhook-endpoints/{id}/test (ensc.webhookEndpoints.sendTest(id, { eventType })) queues one signed event in that endpoint’s environment; every active endpoint there that subscribes to the type receives it, and the response says whether the endpoint you named is among them (willDeliverToTargetEndpoint). With an eventType from the catalogue and no payload, the delivery carries the fields a real event of that type carries; with no eventType it is a synthetic.test_event. A Live endpoint accepts only synthetic.test_event (ENSC_TEST_LIVE_MISMATCH otherwise), so a real event type can never be forged into a Live receiver. POST /v1/test-data/events (ensc.testEvents.emit) sends a realistic event to every Sandbox endpoint, and GET /v1/test-data/events (ensc.testEvents.list) shows the catalogue with a sample payload per type.
4. Read the attempt back with GET /v1/events/{eventId} and confirm status: "delivered" with your 200.

const { eventId, willDeliverToTargetEndpoint } = await ensc.webhookEndpoints.sendTest(endpoint.id, {
  eventType: 'payout.succeeded',
}); // queued in the endpoint's environment; false if this endpoint does not subscribe to the type
await ensc.testEvents.emit({ eventType: 'conversion.requires_manual_review' }); // to every Sandbox endpoint
const detail = await ensc.events.get(eventId);   // each attempt, with your endpoint's HTTP answer

​

Going live