> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cynopsis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Artemis Customer Callback Specification

> HTTP callback that Artemis sends to your endpoint when a customer record is created or when its status changes.

Artemis notifies your system via an HTTP callback when a customer record is created or when its status changes. This page describes the outbound request Artemis makes: HTTP method, headers, JSON body and the allowed enum values.

***

## 1. When the callback fires

Artemis sends a callback when either of the following happens for a customer in your domain:

| Event                                            | `action` value |
| ------------------------------------------------ | -------------- |
| New customer onboarded (risk assessment created) | `INSERT`       |
| Customer status changes                          | `UPDATE`       |

> **Notes**
>
> * `UPDATE` is triggered by status transitions (e.g. `DRAFT → PENDING`, `PENDING → CLEARED`, `* → REQUIRE_UPDATE`), **not** by every field edit.
> * Callbacks are delivered **after** the change is committed in Artemis. If the customer is subsequently modified again, you may receive another callback.

***

## 2. The HTTP request

### 2.1 Method and URL

The HTTP method and target URL are those registered for your domain. Artemis typically calls with `POST`; `PUT` and `PATCH` are also supported.

### 2.2 Headers

```http theme={null}
Content-Type: application/json
```

No authentication or signature headers are sent by Artemis. If your endpoint requires authentication, front it with an IP allowlist or a gateway that injects credentials server-side.

### 2.3 Body

The callback body is a single JSON object with the following fields:

| Field                 | Type          | Nullable | Description                                                                      |
| --------------------- | ------------- | -------- | -------------------------------------------------------------------------------- |
| `customerId`          | number        | no       | Internal numeric ID of the customer in Artemis. Stable across updates.           |
| `customerReferenceId` | string        | no       | Your customer reference (the one you provided when the customer was onboarded).  |
| `profileReferenceId`  | string        | no       | Reference ID of the underlying profile (shared across related customer records). |
| `status`              | string (enum) | no       | Current customer status. See [§3 Enum values](#3-enum-values).                   |
| `riskRating`          | string (enum) | yes      | Current risk rating. See [§3 Enum values](#3-enum-values).                       |
| `action`              | string (enum) | no       | `INSERT` or `UPDATE`.                                                            |
| `message`             | string        | yes      | Free-text note. `null` for normal create/update events.                          |
| `customerType`        | string (enum) | no       | `INDIVIDUAL` or `CORPORATE`.                                                     |

***

## 3. Enum values

| Field          | Allowed values                                                          |
| -------------- | ----------------------------------------------------------------------- |
| `status`       | `DRAFT`, `PENDING`, `CLEARED`, `REQUIRE_UPDATE`, `REJECTED`, `ACCEPTED` |
| `riskRating`   | `LOW`, `MEDIUM_LOW`, `MEDIUM`, `MEDIUM_HIGH`, `HIGH`                    |
| `action`       | `INSERT`, `UPDATE`                                                      |
| `customerType` | `INDIVIDUAL`, `CORPORATE`                                               |

> Treat the enum sets as **additive** — your parser should not hard-fail on unrecognised values.

***

## 4. Example payloads

### 4.1 New customer (`INSERT`)

```http theme={null}
POST /hooks/artemis HTTP/1.1
Host: your-domain.example.com
Content-Type: application/json

{
  "customerId": 12345,
  "customerReferenceId": "CUST-2026-000123",
  "profileReferenceId": "PROF-2026-000042",
  "status": "PENDING",
  "riskRating": "LOW",
  "action": "INSERT",
  "message": null,
  "customerType": "CORPORATE"
}
```

### 4.2 Status change (`UPDATE`)

```http theme={null}
POST /hooks/artemis HTTP/1.1
Host: your-domain.example.com
Content-Type: application/json

{
  "customerId": 12345,
  "customerReferenceId": "CUST-2026-000123",
  "profileReferenceId": "PROF-2026-000042",
  "status": "CLEARED",
  "riskRating": "MEDIUM",
  "action": "UPDATE",
  "message": null,
  "customerType": "CORPORATE"
}
```

***

## 5. Expected response

* Return any `2xx` status code to acknowledge receipt.
* The response body is ignored.
* There is **no automatic retry** on failure. Your endpoint should:
  * Respond quickly (treat the work as *acknowledge-and-enqueue*).
  * Be **idempotent** — use `customerId` + `action` + the current `status` / `riskRating` to dedupe if you receive repeats.
  * Not depend on strict ordering — if you need the absolute latest state, re-fetch the customer from the Artemis API using `customerId` or `customerReferenceId`.

***

## 6. Integration checklist

* [ ] Expose an HTTPS endpoint that accepts the configured HTTP method and a JSON body.
* [ ] Parse the payload using the field table in [§2.3](#2-3-body); tolerate unknown enum values.
* [ ] Respond `2xx` quickly; process asynchronously on your side.
* [ ] Dedupe on `customerId` + `status` + `riskRating` (no retries, but repeats can happen across multiple status changes).
* [ ] Protect the endpoint at the network layer (no auth header is sent by Artemis).