Skip to main content
Legitmark sends three event types. Every webhook destination receives all events automatically.

​
state_change

Sent when a service request transitions to a new state. This is the primary event for tracking authentication progress and results.

​
Payload

{
  "event_type": "state_change",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "state": {
    "primary": "COMPLETE",
    "supplement": "APPROVED"
  },
  "timestamp": "2026-02-10T12:00:00.000Z"
}

​
Fields

​
event_type
string
required
Always "state_change".
​
sr_uuid
string
required
Service request UUID.
​
reference_id
string | null
Your internal item ID — the external_id you set when creating the service request.
​
state
object
required
​
timestamp
string
required
ISO 8601 timestamp of when the state change occurred.

​
State Transitions

The table below shows the state transitions you may receive:
state.primarystate.supplementMeaning
QCPENDINGPhotos submitted, under quality review
QCREJECTEDPhotos failed quality review — a media_rejected event follows with details
QCAPPROVEDPhotos passed QC, authentication starting
UNDERWAYASSIGNEDAuthenticator assigned
COMPLETEAPPROVEDItem is authentic
COMPLETEREJECTEDItem is not authentic
The most important transition is COMPLETE + APPROVED or COMPLETE + REJECTED — this is the final authentication result. See Service Request States for the full state machine.Using the TypeScript SDK (v0.2.0+), you can check these with isAuthentic(event) and isCounterfeit(event) instead of comparing strings manually. See Handling Webhooks.

​
media_rejected

Sent when uploaded images fail quality control. Each rejected image includes the side name and rejection reason so you can prompt the user to re-upload specific photos.

​
Payload

{
  "event_type": "media_rejected",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "sides": [
    {
      "side": "Front",
      "reason": "Image is Blurry",
      "message": "The submitted image is too blurry. Please capture a clearer photo, ensuring minimal motion for better accuracy."
    },
    {
      "side": "Interior",
      "reason": "Insufficient Lighting",
      "message": "The lighting in the submitted image is insufficient. Please take a new photo with better lighting for improved visibility."
    }
  ],
  "timestamp": "2026-02-10T12:15:00.000Z"
}

​
Fields

​
event_type
string
required
Always "media_rejected".
​
sr_uuid
string
required
Service request UUID.
​
reference_id
string | null
Your internal item ID.
​
sides
array
required
Array of rejected images with reasons.
​
timestamp
string
required
ISO 8601 timestamp.
When you receive a media_rejected event, the user needs to re-upload the specific rejected sides before the service request can proceed. Prompt them with the side name and message for the best experience.
Using the TypeScript SDK, needsResubmission(event) returns true for this event type. See Handling Webhooks.

​
invalidate_sr

Sent when a service request is cancelled.

​
Payload

{
  "event_type": "invalidate_sr",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "invalidation_reason": {
    "code": "CANCELLED",
    "message": "Service request cancelled"
  },
  "timestamp": "2026-02-10T14:30:00.000Z"
}

​
Fields

​
event_type
string
required
Always "invalidate_sr".
​
sr_uuid
string
required
Service request UUID.
​
reference_id
string | null
Your internal item ID.
​
invalidation_reason
object
required
​
timestamp
string
required
ISO 8601 timestamp.