Get Case Callbacks

Case Callbacks

Instead of periodically polling the Get Case API, you can configure a callback endpoint to receive case events when a case is created or updated.

Signzy sends the case information to the configured callback URL using a POST request. The data object in the callback uses the same case structure returned by the Get Case API.

Callback Events

Event	Description
CASE_CREATED	Sent when a case is created for a journey
CASE_UPDATED	Sent when an existing case is updated

A CASE_UPDATED event can be generated when the status, priority, risk level, category, assignee or comments are changed. Closing a case is also treated as a case update.

Callback Configuration

The callback URL is configured at the team level.

Request sent to your callback endpoint

Property	Value
Method	POST
Content-Type	application/json
Authorization	Configured callback authentication key, if configured

The callback does not use the per-journey callbackUrl. A case callback is associated with the team because the case can continue to exist after the original journey request has completed.

If no callback URL is configured for the team, no callbacks are sent.

Callback Payload

Sample

{
  "eventType": "CASE_UPDATED",
  "occurredAt": "2026-08-20T09:03:57.655943Z",
  "journeyId": "7QZY374O30",
  "data": {
    "incident_id": "2f642fa9-b298-4f2c-ae82-6da531c9bba5",
    "parent_incident_id": "00000000-0000-0000-0000-000000000000",
    "organization_id": "3d5f8932-ac7f-4831-828b-171d3fec8fcd",
    "team_id": "489700a6-d786-4e43-b145-d483a02f2488",
    "journey_id": "7QZY374O30",
    "flagged": true,
    "status": {
      "lookup_id": "74e9b87a-9cad-447b-b866-8452a0c95d2a",
      "name": "Under Review"
    },
    "priority": "Low",
    "risk_level": {
      "lookup_id": "3dfca4c7-332b-4ea5-bc6b-dc5a6ee49711",
      "name": "Low"
    },
    "category": {
      "lookup_id": "00000000-0000-0000-0000-000000000000",
      "name": ""
    },
    "assigned_to": {
      "user_id": "28e4f20d-7cfd-43cd-8606-e5cb4b8dab92",
      "name": "Rakshanda",
      "email": "[email protected]",
      "phone": "9000000001",
      "job_title": "Compliance Analyst"
    },
    "created_at": "2026-08-12T06:21:37.922266Z",
    "updated_at": "2026-08-20T09:03:57.39199Z",
    "closed_at": null,
    "change_history": []
  }
}

The data object follows the same structure as the result object returned by the Get Case API. This allows you to use the same data model or parser for both API responses and callbacks.

Callback Fields

Field	Type	Description
eventType	String	Event that triggered the callback: CASE_CREATED or CASE_UPDATED
occurredAt	Timestamp	Time at which the event occurred
journeyId	String	Journey associated with the case
data	Object	Current case information

Callback Delivery

Callbacks use at-least-once delivery. The same event can be delivered more than once, so your callback handler should be idempotent.

Use the following combination to identify duplicate deliveries:

journeyId + eventType + occurredAt

Callbacks are not guaranteed to arrive in order. The data object represents the case state at the time of delivery. When maintaining a local copy of the case, compare data.updated_at and retain the latest state.

Retry Behaviour

Each callback attempt has a 10-second timeout.

Signzy retries a failed delivery as follows:

Initial attempt

Retry after 1 second

Retry after a further 2 seconds

If all three attempts fail, the event can be queued for another delivery cycle, with up to three delivery cycles and a maximum of nine POST attempts.

Your Response	Callback Behaviour
2xx	Delivery is considered successful
4xx	Delivery is rejected and is not retried
5xx	Delivery is retried
Timeout	Delivery is retried
Connection error	Delivery is retried

Your endpoint should return a 2xx response as soon as the payload has been accepted. For longer processing, accept the payload and process it asynchronously.

Callbacks should be treated as an asynchronous notification mechanism. The Get Case API remains the source of truth and can be used to reconcile your case data when required.

Integration Recommendation

A typical integration can use the following approach:

Journey
   |
   | Case created / updated
   v
Case Callback
   |
   | Receive CASE_CREATED / CASE_UPDATED
   v
Client System
   |
   | Store / process case information
   |
   +------> GET /otk-service/v1/get-case/{journey_id}
                |
                | Reconciliation / latest case state
                v
           Current Case Data

Recommended implementation

Configure a team-level callback URL.

Implement a POST endpoint to receive CASE_CREATED and CASE_UPDATED.

Return 2xx after successfully accepting the callback.

Make the callback handler idempotent.

Store journeyId, incident_id and updated_at with the case record.

Use updated_at to ensure an older callback does not overwrite a newer case state.

Use the Get Case API to retrieve or reconcile the latest case information when required.

Handle CASE_NOT_FOUND as a valid "no case exists" state rather than an API failure.

One Touch KYC