Webhooks

When a fraud prevention rule is triggered, SmartID sends a request to a REST endpoint hosted by your organization. You must create and expose this web service to receive and process these action requests.

Request Payload

SmartID sends a POST request with the following JSON payload to your webhook endpoint.

Attributes

action integer required

Action to execute. Default actions:

1 = Block user
2 = Close session
3 = Send email
4 = Send SMS
5 = Send email and SMS

These are the default actions. Custom actions can be defined starting from 6 onwards.

channel integer required

Channel identifier.

date datetime required

Date and time when the rule was triggered (ISO 8601 format).

message string required

Message to send to the user, or an HTML template.

reason integer required

Identifier of the rule that was triggered.

session string required

Session identifier.

client string required

Hashed user identifier.

clientRSA string optional

RSA-encrypted user identifier.

Your Webhook Endpoint

POST https://your-domain.com/smartid/webhook

Header: Authorization: Bearer <license_key>

Your webhook endpoint must validate the Bearer token included in every request from SmartID.

JSON — Request

{
  "action": 4,
  "channel": 1,
  "date": "2021-07-28T09:13:35",
  "message": "Login from a new device detected",
  "reason": 12,
  "session": "nmunx32$dsafnwu",
  "client": "bb4e31eedfecacc00cb6...",
  "clientRSA": "g4IRqSFWtn54tIEtrJkA3..."
}

Expected Response

Your service must return the following JSON response:

code integer required

1 = Action executed successfully, 0 = Action not executed.

message string optional

Optional description of the result or error.

JSON — Response

{
  "code": 1,
  "message": "Action executed successfully"
}