Webhook endpoints API

Register webhook endpoints, choose their events, rotate signing secrets, send test deliveries and read delivery results from your own servers.

Call these operations from your own servers with an sk_ server API key that carries the read:webhooks scope (reads) or the write:webhooks scope (changes). Every call is scoped to your organisation, and the endpoints you manage here are the ones the Backoffice shows (Integrations & API, Webhooks): one list.

Scopes. read:webhooks covers every read: GET /v1/webhooks, GET /v1/webhooks/{webhookId}, GET /v1/webhooks/{webhookId}/deliveries and GET /v1/webhooks/event-types. write:webhooks covers every change: creating, updating and deleting an endpoint, rotating its signing secret and sending a test delivery. write:webhooks does not include reading, so a key that manages endpoints needs both. A call without the scope answers 403 with API key does not have read:webhooks scope (or write:webhooks): the message names the missing scope. A key keeps its scopes until a tenant administrator changes them in the Backoffice (API Configuration, Edit scopes on the key: the key id and the secret stay the same and nothing has to be redeployed; an added scope reaches the API within about a minute, a removed scope stops working at once); the other way is to create a new key with the scopes ticked.

The events themselves, their payloads and the delivery rules (headers, signature, retries, deduplication) are described with the API each event belongs to: identity verification (KYC, KYB, KYM), device intelligence (risk scoring, accounts) and the Pulse tenant API. A test delivery with POST /v1/webhooks/{webhookId}/test sends a sample of any of them.

Credential: ApiKeyAuth. See Authentication.

List the events you can subscribe to

GET /v1/webhooks/event-types

Server-to-server. Returns every event type an endpoint can subscribe to, grouped by product (kyc, kyb, kym, risk, account, pulse), in display order, with the name of the data schema each carries. Use it to build a subscription from the live catalog instead of copying event names. identity is true for the events that are delivered only to an endpoint whose signing secret is sealed at rest (every KYC, KYB and KYM session and review event): rotate the secret of an older endpoint once before subscribing it to them.

The payload of every event is documented in the webhooks section of the identity verification API (KYC, KYB, KYM), the device intelligence API (risk and account) and the Pulse tenant API; dataType names the schema.

Authentication: Bearer token (ApiKeyAuth), scope read:webhooks.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "products": [
    "kyc",
    "kyb",
    "kym",
    "risk",
    "account",
    "pulse"
  ],
  "eventTypes": [
    {
      "type": "kyc.session.created",
      "product": "kyc",
      "group": "session",
      "label": "Session created",
      "description": "A hosted KYC session (invitation) was minted.",
      "schemaVersion": "1",
      "dataType": "KycSessionLifecycleData",
      "identity": true
    },
    {
      "type": "kyc.session.completed",
      "product": "kyc",
      "group": "session",
      "label": "Session finished",
      "description": "A hosted KYC session reached a terminal outcome: completed, unverified or error.",
      "schemaVersion": "1",
      "dataType": "KycSessionCompletedData",
      "identity": true
    }
  ],
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/webhooks/event-types" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/event-types', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/event-types",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

List your webhook endpoints

GET /v1/webhooks

Server-to-server. Returns every webhook endpoint of your organisation, the ones registered in the Backoffice and the ones created through this API (one store). The signing secret is never returned. limit is the most endpoints an organisation can register (25).

Authentication: Bearer token (ApiKeyAuth), scope read:webhooks.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "webhooks": [
    {
      "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
      "url": "https://hooks.example.com/noxtica",
      "events": [
        "kyc.session.created",
        "kyc.session.completed",
        "kyc.review.decided"
      ],
      "description": "Onboarding backend",
      "enabled": true,
      "secretSealed": true,
      "createdAt": 1790760000000,
      "updatedAt": 1790760000000,
      "lastDeliveryAt": 1790762445000,
      "lastStatus": "ok"
    }
  ],
  "limit": 25,
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/webhooks" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Register a webhook endpoint

POST /v1/webhooks

Server-to-server. Registers an HTTPS endpoint and the events it receives. The signing secret is returned once, in this response, and never again: store it now. Use rotate-secret to replace it later.

url must be https, without embedded credentials, and must not point at a private, loopback or internal address; the same URL cannot be registered twice. events is the exact list of event types the endpoint receives (see GET /v1/webhooks/event-types): there is no wildcard, no default subscription and an empty list is refused, so list every event you want, and an event type added later is not delivered to an endpoint that did not select it. At most 25 endpoints per organisation. The new endpoint is enabled. The secret is stored encrypted; when encryption is not available for your organisation the call is refused (503 webhook_secret_kek_required) and nothing is written.

Every create, update, delete and rotation is recorded in the organisation’s audit log with your API key as the actor. The endpoints you create here appear in the Backoffice and the other way round.

Authentication: Bearer token (ApiKeyAuth), scope write:webhooks.

Request body

Content type application/json, required.

Responses

Response headers

Response fields (201, application/json)

Response example (201)

{
  "ok": true,
  "webhook": {
    "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
    "url": "https://hooks.example.com/noxtica",
    "events": [
      "kyc.session.created",
      "kyc.session.opened",
      "kyc.session.completed",
      "kyc.review.decided"
    ],
    "description": "Onboarding backend",
    "enabled": true,
    "secretSealed": true,
    "createdAt": 1790760000000,
    "updatedAt": 1790760000000,
    "lastDeliveryAt": null,
    "lastStatus": null
  },
  "secret": "whsec_example_do_not_use_0123456789abcdef",
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/webhooks" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/noxtica",
  "events": [
    "kyc.session.created",
    "kyc.session.opened",
    "kyc.session.completed",
    "kyc.review.decided"
  ],
  "description": "Onboarding backend"
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://hooks.example.com/noxtica',
    events: [
      'kyc.session.created',
      'kyc.session.opened',
      'kyc.session.completed',
      'kyc.review.decided',
    ],
    description: 'Onboarding backend',
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks",
    data=json.dumps({
        "url": "https://hooks.example.com/noxtica",
        "events": [
            "kyc.session.created",
            "kyc.session.opened",
            "kyc.session.completed",
            "kyc.review.decided",
        ],
        "description": "Onboarding backend",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Read a webhook endpoint

GET /v1/webhooks/{webhookId}

Server-to-server. Returns one endpoint of your organisation. The signing secret is never returned. An id of another organisation is indistinguishable from an unknown id (404 webhook_not_found).

Authentication: Bearer token (ApiKeyAuth), scope read:webhooks.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "webhook": {
    "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
    "url": "https://hooks.example.com/noxtica",
    "events": [
      "kyc.session.created",
      "kyc.session.completed"
    ],
    "description": null,
    "enabled": true,
    "secretSealed": true,
    "createdAt": 1790760000000,
    "updatedAt": 1790760000000,
    "lastDeliveryAt": 1790762445000,
    "lastStatus": "ok"
  },
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/webhooks/example-webhookId" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Change a webhook endpoint

PUT /v1/webhooks/{webhookId}

Server-to-server. Partial update: send only the members you change (url, events, description, enabled); at least one is required. events replaces the whole list. Set enabled to false to pause deliveries without losing the endpoint; events that occur while it is disabled are not queued for it. The signing secret is not changed (see rotate-secret).

Authentication: Bearer token (ApiKeyAuth), scope write:webhooks.

Parameters

Request body

Content type application/json, required.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "webhook": {
    "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
    "url": "https://hooks.example.com/noxtica",
    "events": [
      "kyc.session.created",
      "kyc.session.completed",
      "kyb.session.completed"
    ],
    "description": "Onboarding backend",
    "enabled": true,
    "secretSealed": true,
    "createdAt": 1790760000000,
    "updatedAt": 1790763000000,
    "lastDeliveryAt": 1790762445000,
    "lastStatus": "ok"
  },
  "requestId": "req-test"
}

Example request

curl

curl -X PUT "https://collect.noxtica.com/v1/webhooks/example-webhookId" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "kyc.session.created",
    "kyc.session.completed",
    "kyb.session.completed"
  ],
  "enabled": true
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [
      'kyc.session.created',
      'kyc.session.completed',
      'kyb.session.completed',
    ],
    enabled: true,
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId",
    data=json.dumps({
        "events": [
            "kyc.session.created",
            "kyc.session.completed",
            "kyb.session.completed",
        ],
        "enabled": True,
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="PUT",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Delete a webhook endpoint

DELETE /v1/webhooks/{webhookId}

Server-to-server. Deletes the endpoint. Deliveries still waiting for it are dropped.

Authentication: Bearer token (ApiKeyAuth), scope write:webhooks.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
  "removed": true,
  "requestId": "req-test"
}

Example request

curl

curl -X DELETE "https://collect.noxtica.com/v1/webhooks/example-webhookId" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="DELETE",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Rotate the signing secret of an endpoint

POST /v1/webhooks/{webhookId}/rotate-secret

Server-to-server. Mints a new signing secret, returns it once, and stops the previous secret from verifying at once: deliveries sent after this call are signed with the new secret, so update your receiver first or accept both for a moment. The secret is stored encrypted, which is what the session and review events require: rotate an endpoint that was created before encrypted storage once before you subscribe it to them (secretSealed is false until you do). The call has no body.

Authentication: Bearer token (ApiKeyAuth), scope write:webhooks.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "webhook": {
    "id": "7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
    "url": "https://hooks.example.com/noxtica",
    "events": [
      "kyc.session.created",
      "kyc.session.completed"
    ],
    "description": null,
    "enabled": true,
    "secretSealed": true,
    "createdAt": 1790760000000,
    "updatedAt": 1790764000000,
    "lastDeliveryAt": 1790762445000,
    "lastStatus": "ok"
  },
  "secret": "whsec_example_do_not_use_fedcba9876543210",
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/webhooks/example-webhookId/rotate-secret" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId/rotate-secret",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

Send a test delivery to an endpoint

POST /v1/webhooks/{webhookId}/test

Server-to-server. Sends one signed sample delivery of an event type to the endpoint, with the same four headers, envelope and signature as a real delivery, and reports what your receiver answered. Use it to check reachability and signature verification before you rely on an endpoint, and to see the exact payload of any event.

eventType picks the event (any type of GET /v1/webhooks/event-types, whether or not the endpoint subscribes to it); without it the first event of the endpoint is used. The sample carries obvious placeholder data (ids such as test-session), never real data, and its delivery id starts with test_: ignore deliveries with that prefix in your business logic. A test delivery is a single attempt: it is not retried, it is not recorded in the delivery list, and it updates the endpoint’s lastStatus. The test is audited before it leaves. A tighter rate limit than the other operations applies.

The call answers 200 whenever the attempt was made, even when your receiver refused it: read delivered, status and result. The session and review events are signed only with a sealed secret; for an endpoint that does not have one the answer carries error: secret_plaintext_ineligible and nothing is sent: rotate the secret, then test again.

Authentication: Bearer token (ApiKeyAuth), scope write:webhooks.

Parameters

Request body

Content type application/json, optional.

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "delivered": true,
  "eventType": "kyc.session.created",
  "deliveryId": "test_5b8e4d2a-9c61-4a7b-8f35-0e4a7b9d1f35",
  "status": 200,
  "result": "ok",
  "ms": 183,
  "requestId": "req-test"
}

Example request

curl

curl -X POST "https://collect.noxtica.com/v1/webhooks/example-webhookId/test" \
  -H "Authorization: Bearer $NOXTICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eventType": "kyc.session.created"
}'

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    eventType: 'kyc.session.created',
  }),
});
console.log(response.status, await response.text());

Python (standard library)

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId/test",
    data=json.dumps({
        "eventType": "kyc.session.created",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

List recent deliveries of an endpoint

GET /v1/webhooks/{webhookId}/deliveries

Server-to-server. Returns the recent deliveries of KYC, KYB and KYM events to one endpoint, newest first: what happened to each (still retrying, delivered, refused for good, or dead after the retry budget). The list is a notification surface, never authority, and it never holds a URL, a body or a secret: lastError is a closed code. Deliveries of the other products (risk scoring, account and Pulse events) are not listed; their outcome is the endpoint’s lastStatus. Test deliveries are not listed.

Page with cursor: pass the nextCursor of the previous page unchanged; nextCursor is null on the last page.

Authentication: Bearer token (ApiKeyAuth), scope read:webhooks.

Parameters

Responses

Response headers

Response fields (200, application/json)

Response example (200)

{
  "ok": true,
  "deliveries": [
    {
      "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:kyc.session.completed:7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
      "eventType": "kyc.session.completed",
      "state": "delivered",
      "attempts": 1,
      "httpStatus": 200,
      "lastError": null,
      "createdAt": 1790762445000,
      "deliveredAt": 1790762446000
    },
    {
      "id": "6d3c3a8e-6b4b-4a8f-8f4e-0a0e6b3d9d21:kyc.session.review_pending:7f3a2c10-5b8e-4d2a-9c61-0e4a7b9d1f35",
      "eventType": "kyc.session.review_pending",
      "state": "retrying",
      "attempts": 2,
      "httpStatus": 503,
      "lastError": "http_503",
      "createdAt": 1790762400000,
      "deliveredAt": null
    }
  ],
  "nextCursor": null,
  "requestId": "req-test"
}

Example request

curl

curl "https://collect.noxtica.com/v1/webhooks/example-webhookId/deliveries" \
  -H "Authorization: Bearer $NOXTICA_API_KEY"

Node.js (global fetch, Node 18 or later)

const response = await fetch('https://collect.noxtica.com/v1/webhooks/example-webhookId/deliveries', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NOXTICA_API_KEY}`,
  },
});
console.log(response.status, await response.text());

Python (standard library)

import os
import urllib.request

request = urllib.request.Request(
    "https://collect.noxtica.com/v1/webhooks/example-webhookId/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['NOXTICA_API_KEY']}",
    },
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(response.status, response.read().decode())

This page is generated from the Noxtica OpenAPI specification release v0.16.1: v1.yaml version 1.5.1-2026-11-03 (SHA-256 41508500e857). Do not edit it by hand.