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

# List Deliveries

> List recent webhook deliveries for a specific webhook.

## Endpoint

`GET /webhooks/{webhook_id}/events`

Returns a list of recent webhook delivery attempts for the specified webhook. Results are sorted by most recent first.

## Path Parameters

| Parameter   | Type   | Required | Description                                   |
| ----------- | ------ | -------- | --------------------------------------------- |
| webhook\_id | string | Yes      | The ID of the webhook to list deliveries for. |

## Response

Returns a JSON array of delivery objects. Each object contains:

| Field        | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| id           | string | Unique identifier for the delivery event.          |
| event\_type  | string | The type of event delivered.                       |
| timestamp    | string | ISO timestamp of when the delivery occurred.       |
| status\_code | number | HTTP status code returned by the webhook endpoint. |
| request      | object | The request payload sent to the webhook.           |
| response     | object | The response returned by the webhook endpoint.     |

### Example Responses

#### cdd\_state\_changed

```json theme={null}
{
  "id": "54ef493d-7672-4cd8-8080-599601e9609d",
  "event_type": "cdd_state_changed",
  "timestamp": "2025-07-31T02:51:34.155Z",
  "status_code": 500,
  "request": {
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "DiligentAI/1.0",
      "X-Webhook-Id": "df89eb16-4c6a-439f-b668-7cca0cd786fa",
      "X-Event-Id": "54ef493d-7672-4cd8-8080-599601e9609d",
      "X-Customer-Id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "X-Target-type": "CDD",
      "X-Event-Name": "CDD_COMPLETED",
      "X-Signature": "sha256=..."
    },
    "payload": "<CDD object as JSON string>"
  },
  "response": {
    "body": "..."
  }
}
```

* **payload**: The full CDD object as a JSON string. See the [CDD Object documentation](../cdd/cdd-object.mdx) for details.
* **headers**: All headers sent to your endpoint, including:
  * `Content-Type`: Always `application/json`
  * `User-Agent`: Sender identifier
  * `X-Webhook-Id`: Webhook unique ID
  * `X-Event-Id`: Event unique ID
  * `X-Customer-Id`: Authenticated customer ID
  * `X-Target-type`: Always `CDD`
  * `X-Event-Name`: Specific CDD event (e.g., `CDD_COMPLETED`)
  * `X-Signature`: HMAC signature for authenticity

#### monitoring\_alert\_fired

```json theme={null}
{
  "id": "f9e2b3a7-2b4c-4d7d-9a2f-7f7c6f7c6f7c",
  "event_type": "monitoring_alert_fired",
  "timestamp": "2025-07-31T05:12:03.123Z",
  "status_code": 200,
  "request": {
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "DiligentAI/1.0",
      "X-Webhook-Id": "df89eb16-4c6a-439f-b668-7cca0cd786fa",
      "X-Event-Id": "f9e2b3a7-2b4c-4d7d-9a2f-7f7c6f7c6f7c",
      "X-Customer-Id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "X-Target-type": "MONITORING_ALERT",
      "X-Event-Name": "MONITORING_ALERT_FIRED",
      "X-Signature": "sha256=..."
    },
    "payload": {
      "alert_id": "alrt_01HZY9V7FZJQ3K0KZP1YQ9E5X2",
      "monitoring_id": "mon_01HZY9V7FZJQ3K0KZP1YQ9E5X2",
      "type": "FRAUD",
      "details": {
        "reason": "Suspicious activity detected",
        "triggered_at": "2025-07-31T05:12:03.123Z"
      }
    }
  },
  "response": {
    "body": "ok"
  }
}
```

* **payload**: The alert object, with all relevant fields for the alert event.
* **headers**: Same structure as above, with `X-Target-type` as `MONITORING_ALERT` and `X-Event-Name` as `MONITORING_ALERT_FIRED`.

#### flow\_run\_completed

```json theme={null}
{
  "id": "54ef493d-7672-4cd8-8080-599601e9609d",
  "event_type": "flow_run_completed",
  "timestamp": "2025-07-31T10:00:45.000Z",
  "status_code": 200,
  "request": {
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "DiligentAI/1.0",
      "X-Webhook-Id": "df89eb16-4c6a-439f-b668-7cca0cd786fa",
      "X-Event-Id": "54ef493d-7672-4cd8-8080-599601e9609d",
      "X-Customer-Id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "X-Target-type": "FLOW_RUN",
      "X-Event-Name": "FLOW_RUN_COMPLETED",
      "X-Signature": "sha256=..."
    },
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "flow_id": "flow-abc123",
      "flow_version_id": "ver-def456",
      "status": "COMPLETED",
      "input": { "subject": "Acme Corp" },
      "report": "s3://flows-artifacts/reports/run-a1b2c3d4.json"
    }
  },
  "response": {
    "body": "ok"
  }
}
```

* **payload**: The full flow run object (same as `GET /v1/flow-runs/{runId}`).
* **headers**: Same structure as above, with `X-Target-type` as `FLOW_RUN` and `X-Event-Name` as `FLOW_RUN_COMPLETED`.

#### flow\_run\_failed

```json theme={null}
{
  "id": "f9e2b3a7-2b4c-4d7d-9a2f-7f7c6f7c6f7c",
  "event_type": "flow_run_failed",
  "timestamp": "2025-07-31T10:00:12.000Z",
  "status_code": 200,
  "request": {
    "headers": {
      "Content-Type": "application/json",
      "User-Agent": "DiligentAI/1.0",
      "X-Webhook-Id": "df89eb16-4c6a-439f-b668-7cca0cd786fa",
      "X-Event-Id": "f9e2b3a7-2b4c-4d7d-9a2f-7f7c6f7c6f7c",
      "X-Customer-Id": "69df5d81-2b74-4f42-a401-13eb96ba0619",
      "X-Target-type": "FLOW_RUN",
      "X-Event-Name": "FLOW_RUN_FAILED",
      "X-Signature": "sha256=..."
    },
    "payload": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "flow_id": "flow-abc123",
      "flow_version_id": "ver-def456",
      "status": "FAILED",
      "input": { "subject": "Acme Corp" },
      "error": {
        "code": "EXECUTION_ERROR",
        "message": "entityName is required"
      }
    }
  },
  "response": {
    "body": "ok"
  }
}
```

* **payload**: The full flow run object (same as `GET /v1/flow-runs/{runId}`).
* **headers**: Same structure as above, with `X-Target-type` as `FLOW_RUN` and `X-Event-Name` as `FLOW_RUN_FAILED`.

## Errors

### 500 Internal Server Error

Unexpected error occurred.

```json theme={null}
{
  "error": "Internal server error"
}
```

## Authentication

This endpoint requires authentication. Only deliveries for webhooks owned by the authenticated customer are returned.


## OpenAPI

````yaml GET /webhooks/{webhook_id}/events
openapi: 3.0.1
info:
  version: 1.5.0
  title: Diligent
  description: >
    Download Postman collection
    [here](https://docs.godiligent.ai/files/postman_collection.json).
servers:
  - url: https://api.godiligent.ai
    description: Production
  - url: https://api.sandbox.godiligent.ai
    description: Sandbox
security:
  - xApiKey: []
tags:
  - name: CDD
    description: Customer Due Diligence
  - name: Company
    description: Company Information
  - name: Blocked Companies
    description: Manage blocked companies
  - name: Monitorings
    description: Website monitoring and alerts for changes and risks
  - name: Webhooks
    description: >

      ## How to Secure Webhook Deliveries

      To ensure that webhook payloads are securely transmitted and verified.
      This guide explains how to configure and validate

      webhook deliveries using a shared secret.


      ### How It Works


      When setting up a webhook, a secret is configured on both the sender (our
      system) and the receiver (your endpoint). Each

      webhook payload is signed using this secret, allowing the receiver to
      verify its authenticity.


      #### Step 1: Configuring Your Webhook Secret


      1. When creating a webhook in our system, specify a unique secret key.
      This secret should be a strong, randomly

      generated string.

      2. Store this secret securely on your server; it should never be exposed
      publicly.


      #### Step 2: Receiving Webhook Payloads


      When your server receives a webhook event, the request will include an
      `X-Signature` header containing a HMAC signature

      of the payload.


      Example header:


      ```

      X-Signature: sha256=abcdef1234567890...

      ```


      #### Step 3: Validating the Webhook Signature


      To verify the webhook payload:


      1. Retrieve the `X-Signature` value from the request headers.

      2. Compute the HMAC SHA-256 signature of the request payload using your
      webhook secret.

      3. Compare the computed signature with the one in the `X-Signature`
      header.

      4. If they match, the webhook is valid.


      #### (Python)


      ```python

      import hashlib

      import hmac

      import json


      def verify_webhook_signature(secret, payload, signature):
        computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
        expected_signature = f"sha256={computed_signature}"
        return hmac.compare_digest(expected_signature, signature)

      # Example usage:

      secret = "your_webhook_secret"

      payload = json.dumps({"event": "example"})

      received_signature = "sha256=abcdef1234567890..."


      if verify_webhook_signature(secret, payload, received_signature):
        print("Valid webhook received!")
      else:
        print("Invalid webhook signature!")
      ```


      #### (JavaScript)


      ```javascript

      const crypto = require('crypto');


      function verifyWebhookSignature (secret, payload, signature) {

      const computedSignature = `sha256=${crypto.createHmac('sha256', secret)

      .update(payload)

      .digest('hex')}`;

      return crypto.timingSafeEqual(Buffer.from(computedSignature),
      Buffer.from(signature));

      }


      // Example usage:

      const secret = "your_webhook_secret";

      const payload = JSON.stringify({ event: "example" });

      const receivedSignature = "sha256=abcdef1234567890...";


      if (verifyWebhookSignature(secret, payload, receivedSignature)) {

      console.log("Valid webhook received!");

      } else {

      console.log("Invalid webhook signature!");

      }

      ```


      #### Security Considerations


      - Always use HTTPS to prevent interception of webhook payloads.

      - Reject webhook requests that fail signature validation.

      - Rotate secrets periodically to enhance security.


      By following this guide, you ensure that webhook deliveries are secure and
      trusted.
  - name: Instant Screening (experimental)
    description: Instant Website Screening API
  - name: Name Screening
    description: Name screening search, alert management and remediation
paths:
  /webhooks/{webhook_id}/events:
    get:
      tags:
        - Webhooks
      summary: List recent webhook deliveries
      operationId: listWebhookDeliveries
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: Webhook ID to filter deliveries.
          schema:
            type: string
      responses:
        '200':
          description: List of recent webhook delivery events.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    webhook_id:
                      type: string
                      format: uuid
                    event_type:
                      type: string
                    timestamp:
                      type: string
                      format: date-time
                    status_code:
                      type: integer
                      example: 204
                    request:
                      type: object
                      properties:
                        headers:
                          type: object
                        payload:
                          type: object
                    response:
                      type: object
                      properties:
                        headers:
                          type: object
                        body:
                          type: object
components:
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````