Webhooks

The Webhooks section configures notifications for verification events. KnowaKYC sends HTTP requests to the URLs you provide when specific events happen (session created, step completed, verification approved or rejected, and others).

EndpointsCopy Anchor Link

An endpoint is a URL on your server that receives KnowaKYC notifications. You can create several endpoints for different purposes and environments.

Creating an endpointCopy Anchor Link

When you create a new endpoint, set the following parameters:

• URL — the address on your server that receives notifications. HTTPS is required.
• Description — explains the endpoint's purpose (for example, "Production CRM", "Analytics system").
• Environment — sandbox or production. Determines which environment's events are sent to this URL.
• Event types — the list of events to receive notifications for:
  • All events (*) — notifications for every event type.
  • Selected events — a custom set (for example, verification.approved, verification.declined, step.completed).
  • KYB events — events related to business verification (for example, kyb.business.verified) are listed in a separate category.

The full list of event types is in Webhooks API and KYB Webhooks.

Signing secretCopy Anchor Link

After you create the endpoint, the system generates a signing secret with a whsec_ prefix. The secret is used to verify the authenticity of incoming requests on your side.

Rotating the secretCopy Anchor Link

When you need to update the secret (scheduled rotation or suspected compromise):

1. Open the endpoint card.
2. Trigger secret rotation.
3. During the grace period, both secrets (old and new) are accepted simultaneously, which lets you update the signature-check code on your side without losing notifications.
4. When the grace period ends, the old secret stops working automatically. The console shows the deadline with its time zone and refreshes the rotation state.
5. To complete early, first update the receiving integration, then choose Complete rotation and confirm. The old secret stops working immediately. A delivery circuit marked Open is a separate delivery failure; completing rotation does not fix receiver TLS errors.

Delivery logCopy Anchor Link

The "Logs" (or "Deliveries") sub-section shows the notification delivery history:

When you open delivery details you can see the request body, headers, and your server's response. This helps diagnose issues with notification receipt and signature verification.

ResendCopy Anchor Link

For a specific failed delivery, the "Resend" action redelivers the notification to the same endpoint.

Retry policyCopy Anchor Link

When delivery fails (your server did not respond or returned an error code), KnowaKYC retries automatically:

• Maximum attempts — up to 5.
• Strategy — exponential backoff: base delay 5 seconds, doubled on each attempt, capped at 24 hours. A random jitter of ±20% is applied to spread the load.
• When all attempts are exhausted, the event is moved to the dead-letter queue (DLQ) — see below.

Dead-letter queue (DLQ)Copy Anchor Link

The Dead Letter Queue sub-section lists events for which all automatic delivery attempts have been exhausted. Available actions:

• Resend a single event (Retry) — the notification is redelivered to the same endpoint.
• Bulk retry (Retry all) — every event from the DLQ for the chosen endpoint is resent (typically used after the receiver has been restored).
• Delete event (Delete) — the event is removed from the DLQ without being sent.

Every bulk action and retry is recorded in the audit log.

Statistics and payload examplesCopy Anchor Link

• Delivery statistics — summary metrics per endpoint (number of sends, successful deliveries, failures, average response time).
• Payload example for each event type — shows the request body structure sent to the endpoint when the event fires. Use it for offline debugging of your handler code.

TestingCopy Anchor Link

Two tools verify that an endpoint is set up correctly:

PingCopy Anchor Link

Sends a simple request without payload to check that your server is reachable. The result shows whether the endpoint responds and with what HTTP code.

Test eventCopy Anchor Link

Sends a test event with sample data (for example, verification.approved with a test payload). It is used to verify:

• That request routing works correctly on your side.
• That HMAC signature verification works.
• That your application processes the payload structure correctly.

The test send result appears in the delivery log.