⚙️ API Webhooks Integration

We recommend passing a webhook_url when you create each person.

The webhook payload is similar to the person status endpoint, with some additional fields (webhook_request_id, timestamp, and _links).

Key fields

• webhook_url (string): where we POST the webhook when the person’s folder completes.
• webhook_details (boolean, optional): set to true to include report details in the webhook payload. Omit or set to false for status-only payloads.
• webhook_headers (object, optional): custom headers we send to your endpoint. Use these to secure the webhook (e.g., a shared secret you validate).

Example: webhook without details (status only)

export API_KEY="your_api_key"

curl --request POST \
  --url https://api.emptor.io/v3/pe/persons \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $API_KEY" \
  --data '{
    "document_id": "70448431",
    "pipeline": {
      "name": "YOUR_PIPELINE_NAME"
    },
    "webhook_url": "https://example.com/webhooks/emptor",
    "webhook_details": false,
    "webhook_headers": {
      "X-Webhook-Secret": "YOUR_SHARED_SECRET"
    }
  }'

Example: webhook with details enabled

export API_KEY="your_api_key"

curl --request POST \
  --url https://api.emptor.io/v3/PE/persons \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $API_KEY" \
  --data '{
    "document_id": "70448431",
    "pipeline": {
      "name": "YOUR_PIPELINE_NAME"
    },
    "webhook_url": "https://example.com/webhooks/emptor",
    "webhook_details": true,
    "webhook_headers": {
      "X-Webhook-Secret": "YOUR_SHARED_SECRET"
    }
  }'

---

Legacy org-wide webhook mapping (support-assisted)

If you need a single endpoint for your entire organization, or want webhooks for Dashboard-created persons, Emptor support can configure an internal webhook mapping for your org.

Note

Legacy endpoint (support-assisted): https://docs.emptor.io/reference/configure-webhook

Example of information provided to the webhook

{
  "webhook_request_id": "0b6b73d5-c7bb-4124-a520-6bba4a9e8f2b",
  "timestamp": "1693404404191",
  "_links": {
    "person": {
      "href": "https://api.emptor.io/v3/PE/persons/d2dac593-3460-4492-b249-411e5813d9b2",
      "http_methods": [
        "GET"
      ]
    },
    "self": {
      "href": "https://api.emptor.io/v3/PE/reports/d2dac593-3460-4492-b249-411e5813d9b2",
      "http_methods": [
        "GET"
      ]
    }
  },
  "id": "d2dac593-3460-4492-b249-411e5813d9b2",
  "status": "PASSED",
  "custom_data": null,
  "created_at": "2023-08-30T14:01:50.988974",
  "updated_at": "2023-08-30T14:05:38.893452",
  "reports": {
    "document_id_status": {
      "updated_at": "2023-08-30T14:04:13.654999",
      "created_at": "2023-08-30T14:01:50.988974",
      "outcome": "PASSED",
      "state": "COMPLETED"
    },
    "news_search": {
      "updated_at": "2023-08-30T14:05:38.893452",
      "created_at": "2023-08-30T14:01:51.049228",
      "outcome": "INFO",
      "state": "COMPLETED"
    }
  }
}

Schema of data sent via webhook

$schema: http://json-schema.org/draft-07/schema#
description: Similar structure to person status endpoint.
type: object
definitions:
  ReportStatus:
    description: Details for an enabled report.
    properties:
      created_at:
        description: ISO 8601 representation of the date when report started.
        title: Created At
        type: string
      outcome:
        description: Only available if state is `COMPLETED`.
        title: Outcome
        type: string
        enum: [PASSED, FAILED, INFO, null]
      reviewed_at:
        description: Timestamp of performed manual review if available.
        title: Reviewed At
        type: string
      state:
        description: Keyword noting state of report.
        title: State
        type: string
        enum: [COMPLETED, INCOMPLETE, ERROR]
      updated_at:
        description: ISO 8601 representation of the date when report was done running.
        title: Updated At
        type: string
    title: ReportStatus
    type: object
properties:
  webhook_request_id:
    type: string
  timestamp:
    type: string
  _links:
    type: object
    properties:
      person:
        type: object
        properties:
          href:
            type: string
            format: uri
          http_methods:
            type: array
            items:
              type: string
              enum: [GET]
      self:
        type: object
        properties:
          href:
            type: string
            format: uri
          http_methods:
            type: array
            items:
              type: string
              enum: [GET]
  id:
    type: string
  status:
    type: string
    description: Keyword noting state of the folder.
    enum: [PASSED, FAILED, INCOMPLETE, INFO, ERROR]
  custom_data:
    description: Optional additional information provided when person was created.
    title: Custom Data
  created_at:
    description: ISO 8601 representation.
    title: Created At
  updated_at:
    description: ISO 8601 representation of the date all report reached end status.
    title: Updated At
    type: string
  reports:
    additionalProperties:
      $ref: '#/definitions/ReportStatus'
    description: Object containing the reports enabled for this person.
    title: Reports
    type: object