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

# Webhook Integration Guide

## 1. Webhook Subscription

Partners can subscribe to event notifications from **AccessRC** via the `api/Event/Subscribe` endpoint.

### 💡 Example Requests

#### 🔹 No Authentication

```json theme={null}
{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook"
}
```

#### 🔹 API Key Authentication

```json theme={null}
{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "header",
    "headerName": "X-API-Key",
    "headerValue": "my-api-key"
  }
}
```

#### 🔹 Basic Authentication

```json theme={null}
{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "basic",
    "username": "webhook-user",
    "password": "s3cr3t"
  }
}
```

#### 🔹 HMAC Authentication

```json theme={null}
{
  "eventType": "DELIVERY_CHANNEL_STATUS_UPDATED",
  "callbackUrl": "https://partner.example.com/webhook",
  "auth": {
    "type": "hmac",
    "secret": "abcd1234"
  }
}
```

## 2. 🔐 Webhook Request Authentication

AccessRC will send event callbacks to your registered callbackUrl.

Each webhook request will include an authentication header according to your chosen subscription option:

<div className="overflow-x-auto mt-4 mb-4">
  | 🔸 Auth Type | 🔖 Header                     | 🧩 Example                                                           |
  | ------------ | ----------------------------- | -------------------------------------------------------------------- |
  | **None**     | *(no header)*                 | –                                                                    |
  | **API Key**  | `x-api-key`                   | `x-api-key: my-api-key`                                              |
  | **Basic**    | `Authorization`               | `Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=`                      |
  | **HMAC**     | `x-signature` + `x-timestamp` | `x-signature: sha256=abcdef123456...`<br />`x-timestamp: 1717430400` |
</div>

## 3. 🧮 Verifying HMAC Signatures

When using **HMAC authentication**, every webhook request includes an `X-Signature` header and an `X-Timestamp` header:

```http theme={null}
x-signature: sha256=3bdc5b07d7ef9b61b98ed5df4b1793e12fd...
x-timestamp: 1717430400
```

* **`x-signature`** — `sha256=` followed by the hex-encoded HMAC-SHA256 of the raw request body.
* **`x-timestamp`** — the Unix time **in seconds** at which AccessRC sent the request. Use it to reject stale/replayed deliveries (e.g. reject if it is more than a few minutes from your server's current time).

This signature is generated using:

* 🧾 The **raw HTTP request body** (exact bytes, not parsed JSON)
* 🔑 The **shared secret** you provided in your subscription

***

### ✅ Verification Steps

1. **Extract the Signature**\
   Read the `x-signature` header from the incoming request.

2. **Get the Raw Request Body**\
   Use the exact raw payload as received — do not reformat or parse.

3. **Recompute the Signature**\
   Use `HMAC-SHA256(secret, rawBody)` to generate your own hash.\
   Prefix it with `"sha256="`.

4. **Compare Signatures**\
   Compare your computed signature with the received one.

***

## 4. 🔒 Security Best Practices

* 🚫 **Never log or expose the shared secret.**
* ✅ **Always verify signatures** for HMAC webhooks.
* 🔍 **Reject any unsigned or invalid webhook requests.**
* 🌐 **Always use HTTPS** for your webhook endpoint.
* 🧱 Keep your secret in secure configuration storage (not in code or client apps).

***

## 5. 🧪 Testing Webhooks

To test locally and ensure your webhook integration works as expected:

1. 🌍 Use a tool like **ngrok** or **localtunnel** to expose your local webhook endpoint publicly.
2. 🪵 Log incoming request **headers** and the **raw body** for debugging.
3. 🔑 Simulate signature generation manually using your shared secret to validate your implementation.
4. 🧩 Verify your signature verification logic before deploying to production.
5. 🔁 Test retry scenarios by sending multiple requests and validating idempotency.

> 💡 **Tip:** When testing, return different HTTP status codes (200, 401, 403) to confirm AccessRC handles each scenario as expected.

***

## 6. 📬 Response Expectations

Your webhook endpoint should behave as follows:

* ✅ **Return `HTTP 2xx`** (usually `200 OK`) when processing succeeds.
* 🔐 **Return `401 Unauthorized`** if signature or authentication validation fails.
* ⏱️ **Respond quickly** (within a few seconds) — delayed responses may trigger retries.
* 🧾 Include a short, plain-text or JSON response body if helpful for debugging, but it’s optional.

### 💬 Example Responses

#### ✅ Success

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "message": "Callback successfully received",
  "data": {}
}
```

#### ❌ Invalid Signature (HMAC)

```http theme={null}
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid Signature",
     "type": "Unauthorized"
  }
}
```

#### 🚫 Invalid API KEY

```http theme={null}
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid API KEY",
     "type": "Unauthorized"
  }
}
```

#### 🚫 Invalid Credentials

```http theme={null}
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": "failed",
  "error": {
     "code": 401,
     "message": "Invalid Credentials",
     "type": "Unauthorized"
  }
}
```