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

# Webhook

> Network communication architecture and data security policies for the Webhook channel through which ARGOS Identity delivers verification results to customers.

## 1. Document Overview

### 1.1 Purpose

This document describes the network communication architecture and security policies for the channel through which ARGOS Identity delivers verification results to customers via **Webhook (callback)**.

### 1.2 Target Audience

* Information security and security review personnel at customer organizations
* Development teams building and operating Webhook receiving endpoints
* Compliance / audit departments

### 1.3 Scope

* Webhook dispatch communication from ARGOS → customer
* Communication protocol, TLS, payload encryption
* Authentication, integrity, retry, and auditing

***

## 2. Service Category Introduction

**Webhook** is the channel through which ARGOS delivers KYC processing results (approved / rejected / re-requested, etc.) to customers **asynchronously**.

### 2.1 Features

* **Event-driven**: dispatched immediately when a result is produced (no polling required)
* **HTTPS compliant**: customers can receive events with a standard HTTP server without installing a separate SDK
* **Two-stage pipeline structure**:
  1. **Event convergence layer** (serverless): determines dispatch targets + constructs the body
  2. **Dispatch execution layer** (dedicated dispatch server): executes HTTPS POST to the customer endpoint

### 2.2 Dispatch Triggers

| Event                       | Dispatch Timing                                                    |
| --------------------------- | ------------------------------------------------------------------ |
| Verification completed      | Immediately after a result is finalized via Liveform / Restful API |
| Verification status changed | When a re-verification or supplemental request occurs              |
| Administrator action        | When a manual approval/rejection action occurs in the dashboard    |

***

## 3. Network Communication Flow

### 3.1 Full Flow

```mermaid theme={null}
flowchart TD
    K[KYC verification result finalized] -->|AWS call<br/>SigV4| C["Webhook event convergence layer<br/>- Query project options<br/>- Construct dispatch body<br/>- Apply encryption option (optional)"]
    C -->|AWS call| S[Webhook dispatch execution layer]
    S -->|HTTPS POST<br/>TLS 1.2+| E[Customer Webhook receiving endpoint]
    E -->|HTTP 200 OK / Non-2xx| L[Dispatch result audit log written]
```

### 3.2 Outbound Dispatch Channel

| Item                   | Value                                                                           |
| ---------------------- | ------------------------------------------------------------------------------- |
| Direction              | ARGOS → Customer (Outbound from ARGOS)                                          |
| Protocol               | HTTPS (TLS 1.2 or higher enforced)                                              |
| HTTP Method            | POST (may vary based on customer configuration)                                 |
| Content-Type           | `application/json` (default) / `text/plain` (when encryption option is enabled) |
| Certificate validation | ARGOS validates the customer's certificate (`rejectUnauthorized` enabled)       |

***

## 4. Communication Protocols and Standards

### 4.1 Transport Layer

* **TLS 1.2 or higher** (explicitly enforced in the HTTPS Agent: `secureProtocol: TLSv1_2_method`)
* The customer server's certificate is validated against the standard PKI trust chain (Root CA)
* Self-signed certificates are not supported without prior arrangement

### 4.2 Request Headers

| Header                | Value / Description                                                     |
| --------------------- | ----------------------------------------------------------------------- |
| `Content-Type`        | `application/json` (default), `text/plain` (when encryption is applied) |
| `User-Agent`          | ARGOS internal identifier (e.g., `Argos-kyc-webhook`)                   |
| `X-Webhook-Encrypted` | `true` / `false` — signals whether body encryption is applied           |

### 4.3 Request Body (JSON, plain-text mode)

```json theme={null}
{
  "projectId": "<project identifier>",
  "submissionId": "<submission identifier>",
  "userId": "<optional>",
  "status": "approved | rejected | incomplete",
  "timestamp": "<dispatch timestamp>",
  "webhookParams": { ... }
}
```

The body structure may vary partially depending on project options and the type of dispatch event. For the detailed specification, refer to the separate API documentation.

***

## 5. Data Encryption

### 5.1 Encryption in Transit (Required)

* **TLS 1.2 or higher enforced** (HTTPS only)
* Plain HTTP dispatch is not supported

### 5.2 Payload Encryption (Optional, per-project activation)

Customers who want additional security can apply **encryption on top of TLS** to the body.

| Item           | Value                                                |
| -------------- | ---------------------------------------------------- |
| Activation     | Enable the `Data Encryption` project option          |
| Algorithm      | AES-256 (symmetric key encryption)                   |
| Key derivation | Per-project API Key-based key derivation             |
| Signal header  | `X-Webhook-Encrypted: true`                          |
| Content-Type   | `text/plain` (Base64-encoded ciphertext transmitted) |

**Decryption procedure (customer side)**:

1. Check the `X-Webhook-Encrypted` header
2. Obtain the body (Base64 decode → ciphertext)
3. Derive the key using the project API Key as a seed
4. AES-256 decryption → JSON parsing

***

## 6. Authentication and Authorization

### 6.1 Customer-Side Sender Verification Options

| Method                                           | Description                                                                                                           |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **TLS certificate + sender domain verification** | The customer verifies the origin via the TLS certificate of the ARGOS dispatch domain                                 |
| **IP allowlist (recommended)**                   | Only the fixed IP range of the ARGOS dispatch server is permitted to deliver events (customer firewall configuration) |
| **Encryption mode header**                       | Source confirmed by verifying `X-Webhook-Encrypted: true` and ability to decrypt                                      |
| **Customer-registered authentication header**    | By arrangement, ARGOS can include a customer-specified authentication header (e.g., Bearer token) in the dispatch     |

<Tip>Customers requiring strong sender verification are recommended to use the combination of **IP allowlist + payload encryption mode**.</Tip>

### 6.2 ARGOS Internal Authentication

* Verification layer → Webhook convergence layer: AWS internal call (IAM Role + SigV4)
* Webhook convergence layer → Dispatch execution layer: AWS network call

***

## 7. Integrity and Tamper Prevention

| Segment                   | Integrity Assurance Method                            |
| ------------------------- | ----------------------------------------------------- |
| TLS channel               | TLS 1.2+ built-in integrity (AEAD / HMAC)             |
| Payload (encryption mode) | AES-256 + successful decryption = source verification |
| TCP transport             | TCP checksum + TLS end-to-end integrity               |
| Dispatch log              | Append-only audit table entries (immutable)           |

***

## 8. Access Control and Isolation

### 8.1 Dispatch Target Isolation

* Customer Webhook URLs are **registered and isolated per project**
* Explicit registration procedure requiring administrator authentication when the URL is changed

### 8.2 Dispatch Server Isolation

* The ARGOS Webhook dispatch server operates within AWS exclusively for **result notification**
* Direct inbound requests to this server from outside are not possible
* Dispatch targets are limited to customer-registered URLs only

### 8.3 Environment Separation

* Live / Test environment dispatch channels are separated
* Test results are dispatched only to the registered URL in the test environment

***

## 9. Logging and Auditing

### 9.1 Per-Dispatch Log

Every Webhook dispatch attempt is recorded in the audit table with the following information:

| Item                | Description                           |
| ------------------- | ------------------------------------- |
| Dispatch identifier | Unique ID for the individual dispatch |
| Project identifier  | Project ID                            |
| Dispatch timestamp  | UTC timestamp                         |
| Target URL          | Customer-registered endpoint          |
| HTTP response code  | 200 / 4xx / 5xx                       |
| Response body       | Customer response                     |
| Status              | SUCCESS / FAIL / ERROR                |

### 9.2 Daily Aggregate Metrics

Daily counts of successes, failures, and errors are aggregated in a separate metrics table.

### 9.3 Retry Policy

| Stage               | Policy                                                          |
| ------------------- | --------------------------------------------------------------- |
| First attempt       | Dispatched immediately                                          |
| Retry               | Up to 3 times (exponential backoff)                             |
| DLQ / Manual Replay | Failed dispatches can be manually re-sent using a separate tool |

### 9.4 Retention

* Retention period for dispatch audit logs is defined separately according to compliance requirements

***

## 10. Compliance

### 10.1 ARGOS Identity Held Certifications

* **ISO/IEC 27001** — International standard certification for information security management systems

### 10.2 AWS Infrastructure Certifications (Inherited)

The Webhook dispatch infrastructure (AWS Lambda, EC2, DynamoDB, etc.) inherits the following AWS certifications:

* SOC 1 / SOC 2 / SOC 3
* ISO 27001 / 27017 / 27018
* PCI-DSS Level 1
* HIPAA Eligible
* FedRAMP Moderate

### 10.3 Data Processing Agreement

* Information entrusted by customers to ARGOS for KYC processing is not used for any purpose other than the result notification (Webhook) after processing is complete.
* The policy for cleaning up dispatch audit logs after notification is subject to a separate processing agreement.

***

## Appendix A. Glossary

| Term                | Definition                                                                                |
| ------------------- | ----------------------------------------------------------------------------------------- |
| Webhook             | An asynchronous callback method that notifies results via HTTPS POST when an event occurs |
| TLS                 | Transport Layer Security                                                                  |
| AES-256             | 256-bit Advanced Encryption Standard                                                      |
| DLQ                 | Dead Letter Queue (separate channel for retaining failed messages)                        |
| Exponential Backoff | A method of progressively increasing the interval between retries                         |
| Base64              | Binary-to-text-safe encoding                                                              |
| IP allowlist        | A policy that restricts receiving/sending to only permitted IP addresses                  |

***

## Appendix B. Recommended Integration Guide

When customers build ARGOS Webhook receiving endpoints, the following practices are recommended:

1. **Use HTTPS-only endpoints** (Let's Encrypt / commercial certificate)
2. **Allow only the ARGOS dispatch IP range** (firewall/security group configuration)
3. **Enable `X-Webhook-Encrypted: true` mode** (activate Data Encryption in project options)
4. **Respond with 200 OK immediately** upon receipt, then process asynchronously (delays over 3 seconds may trigger a retry)
5. **Idempotency handling**: ensure safe processing even when the same `submissionId` is received more than once

***

## Appendix C. Contact

For technical inquiries regarding this document, please contact ARGOS Identity through the sales or technical support channel.