Webhook V2

Webhook v2 is a key update to our notification system, designed to provide greater security and granularity for events in the Magic Link flow.

The previous version (v1), configured within the Magic Link request's metadata, became unscalable: it lacked authentication and could only send the generic track and results events.

Webhook v2 solves this:

• Security and Authentication: Webhook v2 configuration requires an active Service Account (provided by Unico) to ensure you receive events securely.

• Scalability and Detail: It is designed to allow sending more detailed events in the future. For example, you will now be able to obtain specific information such as the document capture's re-take reason, a detail that was inaccessible in v1.

Considerations

Webhook v2 configuration is not done directly via the API.

• Configuration Precedence: To ensure compatibility with existing integrations, the webhook configuration set in the metadata of a Magic Link request (v1) will always take the highest precedence over any Webhook v2 configuration.

• No Overriding: The global Webhook v2 configuration does not override webhook configurations made directly via the API for specific Magic Links.

Configuration parameters

Activation: Request configuration from your assigned Onboarding Project Manager, providing:

• URL: The url to use as a webhook.

• Auth type: The type of authentication for the webhook (basic_auth, api_key, oauth2 or NoAuth):

  • basic_auth: Requires user and password.

  • api_key: Requires the header name and header value.

  • oauth2: Requieres the url to authenticate, the client_id and the client_token.

  • NoAuth: Does not perform any type of authentication.

• Auth config: The configuration mentioned before.

• Max retry attemps: The max number of attempts to make a request to the webhook.

• Retry interval seconds: The wait time to retry the request to the webhook.

• Timeout seconds: The TTL before ending the connection to the webhook.

Webhook Events

Currently we only support 3 types of events:

1- MAGIC_LINK_RESULTS

This event is sent at the end of the flow, when the Decision Maker has finished processing the information sent. This is an example of the request sent to the webhook:

{
  "data": {
     "images":{
        "document_image": "base64str",
        "document_image_back": "base64str",
        "selfie": "base64str"
     },
     "response":{
        "document":{
           "details":{
              "detected": bool,
              "forensics":{
                 "is_valid":"str" # "yes", "no", "inconclusive"
              },
              "document_id": int
           },
           "front":{
              "information":{
                 "birthdate":{
                    "text": "str", # format dd/mm/yyyy
                    "valid": bool
                 },
                 "sex":{
                    "text": "str", # "H", "M"
                    "valid": bool
                 },
                 "registration_year":{
                    "text": "str",
                    "valid": bool
                 },
                 "name":{
                    "text": "str",
                    "valid": bool
                 },
                 "mother_last_name":{
                    "text": "str",
                    "valid": bool
                 },
                 "last_name":{
                    "text": "str",
                    "valid": bool
                 },
                 "electoral_key":{
                    "text": "str",
                    "valid": bool
                 },
                 "curp":{
                    "text": "str",
                    "valid": bool
                 },
                 "address":{
                    "text": "str",
                    "valid": bool
                 },
                 "complete_name":{
                    "text": "str",
                    "valid": bool
                 },
                 "valid_thru":{
                    "text": "str",
                    "valid": bool
                 }
              },
              "face_analysis":{
                 "face_id": int,
                 "first_seen": "str", # format "dd/mm/yyyy, hh:mm:ss"
                 "unique_face_id_v2": int,
                 "face_id_v2": int,
                 "inquiry_date": "str", # format "dd/mm/yyyy, hh:mm:ss"
                 "last_seen": "str", # format "dd/mm/yyyy, hh:mm:ss"
                 "last_seen_by_your_company": "str", # format "dd/mm/yyyy, hh:mm:ss"
                 "match": bool,
                 "match_fraud_flag": bool,
                 "seen_by_your_company": bool,
                 "seen_different_companies": int,
                 "times_seen_by_your_company": int,
                 "times_seen_last_month": int,
                 "warnings":{
                    "external_id":"User found in the company with other external_ids: ['123', '12345']"
                 }
              }
           },
           "back":{
              "mrz": "str",
              "cic": "str"
           }
        },
        "selfie":{
           "face_id": int,
           "first_seen": "str", # format "dd/mm/yyyy, hh:mm:ss"
           "unique_face_id_v2": int,
           "face_id_v2": int,
           "inquiry_date": "str", # format "dd/mm/yyyy, hh:mm:ss"
           "last_seen": "str", # format "dd/mm/yyyy, hh:mm:ss"
           "last_seen_by_your_company": "str", # format "dd/mm/yyyy, hh:mm:ss"
           "match": bool,
           "match_fraud_flag": bool,
           "seen_by_your_company": bool,
           "seen_different_companies": int,
           "times_seen_by_your_company": int,
           "times_seen_last_month": int,
           "warnings":{
              "external_id":"User found in the company with other external_ids: ['123', '12345']"
           }
           "first_seen_image": bool
        },
        "face_match": bool,
        "curp":{
           "curp": "str",
           "state_of_birth": "str",
           "state_iso": "str",
           "date_of_birth": "str", # format dd/mm/yyyy
           "age": int,
           "gender": "str",
           "is_mexican": bool,
           "name_to_CURP_valid": bool,
           "government_valid": bool,
           "government_name": "str",
           "deceased": bool
        },
        "unico":{
           "process_id": "str", # format uuid
           "result": bool
        },
        "label": null
        "reason": null,
        "request_id": "str"
     },
     "user_id": "str" || null
  }
  "event": "MAGIC_LINK_RESULTS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str" # 2025-10-03T21:15:41.299815
}

2 - MAGIC_LINK_TRACK

These events are received when the user completed an action, for example, form_start will be received when the user is taking the front document, which means that the user clicked and completed the first screen

{
  "data": {
    "completed_on": "datetime_str", #Fri, 03 Oct 2025 21:15:35 GMT
    "started_on": "datetime_str",
    "step": "form_start", 
    "user_id": null
  },
  "event": "MAGIC_LINK_TRACK",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str" # 2025-10-03T21:15:41.299815
}

Key Table

Key	Description
step	Name of the previous completed step.
user_id	The external_id you set in the magic link.
started_on	UTC timezone. Step starting time.
completed_on	UTC timezone. Step completion time.

Steps Table

Steps	Description
form_start	The user clicked the first magic link button presented on the screen
form_document_front	The user has completed the INE front process
form_document_back	The user has completed the INE back process
form_document	The user has completed both front and back processes
form_selfie	The user has completed the liveness process
form_decision_maker	The user has completed the flow

3 - MAGIC_LINK_DOCUMENT_RETAKE_REASONS

This event is sent when a document re-capture is required, either during the front or back process. It indicates that critical data from the INE could not be read.

{
  "data": {
    "document_type": "str", # "ine_front" || "ine_back" Side of the document that failed
    "invalid_back_ocr": bool, # If true can't read MRZ code (failure only for ine_back)
    "invalid_curp": bool, # If true, can't read CURP (failure only for ine_front).
    "invalid_document": bool # If true, the document is not an INE (failure on either side)
  },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str"
}

Error Combinations and Examples (Payloads)

The payload is designed so that only one error (true) is received for each document side. The specific examples are shown below:

Failures on the Document Front (document_type: "ine_front")

• Invalid Document

{
  "data": {
"document_type": "ine_front",
    "invalid_back_ocr": false,
    "invalid_curp": false,
    "invalid_document": true
    },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str"
}

• CURP Reading Failure

{
  "data": {
    "document_type": "ine_front",
    "invalid_back_ocr": false,
    "invalid_curp": true,
    "invalid_document": false
    },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str"
}

Failures on the Document Back (document_type: "ine_back")

• Invalid Document

{
  "data": {
    "document_type": "ine_back",
    "invalid_back_ocr": false,
    "invalid_curp": false,
    "invalid_document": true
    },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str"
}

• MRZ Reading Failure (OCR)

{
  "data": {
    "document_type": "ine_back",
    "invalid_back_ocr": true,
    "invalid_curp": false,
    "invalid_document": false
    },
  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",
  "magic_link_token": "uuid",
  "user_id": "str" || null,
  "date": "datetime_str"
}