Webhooks

This section covers webhooks, used to react to events that happen in your customers' KYC and KYB. Webhooks are a low-effort way to build integrations that extend Synaps's functionality.

See the Quickstart

---

info

We use Hookdeck to ensure reliable webhook delivery.

If you need to whitelist IP addresses for security purposes, you can find a list of IPs here.

Sensitive Data

We don't disclose any private information through the webhook. You should always make a call to the API in order to fetch user sensitive data.

Secret

We include a secret value as a query parameter in the POST request.

This secret is unique to your app and can be found in your manager. Use it to verify the authenticity of incoming webhooks and ensure that they originate from Synaps.

Payload

All webhook types share a common payload, formatted as a JSON object containing the following fields:

warning

For the corporate (KYB) sessions, the service and step_id field will never be present.

name	type	description	additional information
reason	string	The rejection reason.	⚠️ May be empty in case no rejection occurred.
service	string	One of the individual steps for KYC.	⚠️ May be empty in case of an event not linked to a specific step (e.g. RESET).
session_id	string	The session identifier.	-
status	string	One of the status.	-
step_id	string	This is the step identifier, used to fetch sensible data from the Synaps Core API.	-

Example:

{
  "reason": "The document image seems to be forged",
  "service": "PROOF_OF_ADDRESS",
  "session_id": "2ac3f7ab-3729-f968-3f55-aa47e881",
  "status": "PENDING_VERIFICATION",
  "step_id": "1253242"
}

Event Types (status)

info

Note that this list may be updated (additively) later; therefore, you should gracefully handle unexpected webhook types by discarding them.

Webhooks are triggered when transitionning from one status to another. And the new status is the one sent in the payload.

name	description	additional information
PENDING_VERIFICATION	Sent each time a user has submitted a step (Uploaded a new doc for example.	-
RESUBMISSION_REQUIRED	Sent when a user has been rejected and the session requires a new submission.	The reason field will be present in the payload.
REJECTED	Sent when a user has been rejected for a reason that will not allows further submission.	The reason field will be present in the payload.
RESET	Sent when a user's session has been reset by an administrator.	-