---
title: Get Case Callbacks
slug: one-touch-kyc/get-case-callbacks
createdAt: 2026-09-02T17:43:17.094Z
---

# 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

```json
{
  "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": "rakshanda@yourcompany.com",
      "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:

```text
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:

1. Initial attempt
2. Retry after 1 second
3. 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:

```text
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

1. Configure a team-level callback URL.
2. Implement a `POST` endpoint to receive `CASE_CREATED` and `CASE_UPDATED`.
3. Return `2xx` after successfully accepting the callback.
4. Make the callback handler idempotent.
5. Store `journeyId`, `incident_id` and `updated_at` with the case record.
6. Use `updated_at` to ensure an older callback does not overwrite a newer case state.
7. Use the Get Case API to retrieve or reconcile the latest case information when required.
8. Handle `CASE_NOT_FOUND` as a valid "no case exists" state rather than an API failure.
