⚙️ Integración de Webhooks API

Recomendamos enviar un webhook_url cuando creas cada persona.

El payload del webhook es similar al endpoint de estado de la persona, con algunos campos adicionales (webhook_request_id, timestamp y _links).

Campos clave

webhook_url (string): a dónde hacemos POST cuando se completa la carpeta de la persona.
webhook_details (boolean, opcional): establece true para incluir detalles de reportes en el payload. Omite o usa false para payload solo de estado.
webhook_headers (object, opcional): headers personalizados que enviamos a tu endpoint. Úsalos para asegurar el webhook (por ejemplo, un secreto compartido que validas).

Ejemplo: webhook sin detalles (solo estado)

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"
    }
  }'

Ejemplo: webhook con detalles habilitados

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"
    }
  }'

Mapeo de webhook a nivel de organización (asistido por soporte)

Si necesitas un único endpoint para toda tu organización, o quieres webhooks para personas creadas en el Dashboard, el soporte de Emptor puede configurar un mapeo interno de webhook para tu organización.

Ejemplo de información proporcionada al 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"
    }
  }
}

Esquema de datos enviados vía webhook

$schema: http://json-schema.org/draft-07/schema#
description: Estructura similar al endpoint de estado de persona.
type: object
definitions:
  ReportStatus:
    description: Detalles para un reporte habilitado.
    properties:
      created_at:
        description: Representación ISO 8601 de la fecha cuando el reporte comenzó.
        title: Created At
        type: string
      outcome:
        description: Solo disponible si el estado es `COMPLETED`.
        title: Outcome
        type: string
        enum: [PASSED, FAILED, INFO, null]
      reviewed_at:
        description: Timestamp de revisión manual realizada si está disponible.
        title: Reviewed At
        type: string
      state:
        description: Palabra clave que indica el estado del reporte.
        title: State
        type: string
        enum: [COMPLETED, INCOMPLETE, ERROR]
      updated_at:
        description: Representación ISO 8601 de la fecha cuando el reporte terminó de ejecutarse.
        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: Palabra clave que indica el estado de la carpeta.
    enum: [PASSED, FAILED, INCOMPLETE, INFO, ERROR]
  custom_data:
    description: Información adicional opcional proporcionada cuando se creó la persona.
    title: Custom Data
  created_at:
    description: Representación ISO 8601.
    title: Created At
  updated_at:
    description: Representación ISO 8601 de la fecha cuando todos los reportes alcanzaron el estado final.
    title: Updated At
    type: string
  reports:
    additionalProperties:
      $ref: '#/definitions/ReportStatus'
    description: Objeto que contiene los reportes habilitados para esta persona.
    title: Reports
    type: object