Send events to Ontre

Overview

An admin creates a connection for a project. Your backend sends signed requests to that connection’s stable URL. Ontre verifies the signature before reading the event and returns 202 after an active connection has stored it.

The URL identifies the connection. The workspace signing key proves that the request came from your backend. Keep the key on the server.

Set up a connection

Project admins can create a connection with POST /api/v1/projects/{projectId}/connections and a JSON body containing displayName. The response includes id, postTo, and signingKey status. The workspace key is available through authenticated GET /api/v1/connections/signing-key when ready.

The creation response also includes a token shown only once. The project URL uses the connection ID, so store the postTo path for delivery.

Request and headers

For an older workspace connection created at POST /api/v1/connections, use its returned /webhooks/v1/{connectionToken} path. The headers, payload, and signing process are the same.

Event payload

Send a single JSON object. An events array is rejected.

{
  "source": "checkout-api",
  "eventType": "payment.failed",
  "eventId": "evt_2f9a",
  "occurredAt": "2026-09-16T14:05:00Z",
  "correlationId": "order_88f2",
  "attributes": {
    "amount": 4200,
    "currency": "NGN",
    "errorCode": "gateway_timeout"
  }
}

Sign each request

Serialize the JSON body first. Compute HMAC-SHA256 over the UTF-8 bytes of the Unix timestamp, one period, and the exact body you will transmit. Put the lowercase hex digest in X-Ontre-Signature.

{timestamp}.{rawBody}

Use the same timestamp in the header and signed input. Ontre accepts a clock difference of up to five minutes. For every retry, create a new timestamp and signature without changing the event ID. Do not reformat the body after signing.

Node.js example

Set ONTRE_BASE_URL, ONTRE_WEBHOOK_PATH (the returned postTo path), and ONTRE_SIGNING_KEY in your server environment. Use the signing key as its UTF-8 text value.

import { createHmac } from 'node:crypto';

const baseUrl = process.env.ONTRE_BASE_URL;
const webhookPath = process.env.ONTRE_WEBHOOK_PATH;
const signingKey = process.env.ONTRE_SIGNING_KEY;
if (!baseUrl || !webhookPath || !signingKey) {
  throw new Error('Missing Ontre configuration');
}

const body = JSON.stringify({
  source: 'checkout-api',
  eventType: 'payment.failed',
  eventId: 'evt_2f9a',
  occurredAt: new Date().toISOString(),
  correlationId: 'order_88f2',
  attributes: { amount: 4200, currency: 'NGN' }
});
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = createHmac('sha256', signingKey)
  .update(timestamp + '.' + body, 'utf8')
  .digest('hex');

const response = await fetch(new URL(webhookPath, baseUrl), {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json; charset=utf-8',
    'X-Ontre-Timestamp': timestamp,
    'X-Ontre-Signature': signature
  },
  body
});
if (response.status !== 202) {
  throw new Error('Ontre returned ' + response.status + ': ' + await response.text());
}

Generate a new eventId for each business event. A retry keeps that ID and uses a fresh request timestamp and signature.

Responses and retries

Queue events until you receive 202. Ontre deduplicates by workspace, source, and eventId. Delivery order does not determine event time; occurredAt does.

Connection lifecycle

An admin can suspend or activate a project connection through authenticated endpoints:

Both return 204 on success. GET /api/v1/projects/{projectId}/connections lists status and the postTo path. Disabling a connection stops delivery to that URL.