Crear webhook

POST /v1/webhooks

Registra una URL de webhook para recibir solicitudes POST cuando ocurran eventos de extracción. Cada usuario puede tener hasta 10 webhooks activos.

Pruébalo

Prueba este endpoint de forma interactiva en la Swagger UI.

Autorización requerida

Incluye tu clave API en el encabezado Authorization.

Solicitud

Encabezados

Encabezado	Valor	Requerido
Authorization	Bearer <token>	Sí
Content-Type	application/json	Sí

Cuerpo

Campo	Tipo	Requerido	Descripción
url	string	Sí	Endpoint HTTPS que recibirá las solicitudes POST del webhook.
events	string[]	Sí	Eventos a los que suscribirse. Se requiere al menos uno. Valores: "extraction.completed", "extraction.failed".

Ejemplos de código

curl

curl -X POST https://api.docmap.io/v1/webhooks \
  -H "Authorization: Bearer dm_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/docmap",
    "events": ["extraction.completed", "extraction.failed"]
  }'

TypeScript

const apiKey = process.env.DOCMAP_API_KEY

const response = await fetch('https://api.docmap.io/v1/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/docmap',
    events: ['extraction.completed', 'extraction.failed'],
  }),
})

const { data } = await response.json()

// IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
console.log('Signing Secret:', data.secret)
console.log('Webhook ID:', data.webhook.id)

Python

import requests

api_key = "dm_live_abc123def456ghi789jkl012mno345"

response = requests.post(
    "https://api.docmap.io/v1/webhooks",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/docmap",
        "events": ["extraction.completed", "extraction.failed"],
    },
)

data = response.json()["data"]

# IMPORTANT: Store the signing secret immediately — it cannot be retrieved later
print(f"Signing Secret: {data['secret']}")
print(f"Webhook ID: {data['webhook']['id']}")

Respuesta

Estado: 200 OK

El cuerpo de la respuesta está envuelto en un objeto data.

WARNING

El secreto de firma solo se devuelve en esta respuesta. Almacénalo de forma segura inmediatamente -- no se puede recuperar después. Lo necesitas para verificar las firmas de los webhooks.

Campos

Campo	Tipo	Descripción
secret	string	Secreto de firma HMAC-SHA256 (64 caracteres hexadecimales). Solo se muestra una vez.
webhook	object	Objeto de metadatos del webhook (ver abajo).

Objeto webhook:

Campo	Tipo	Descripción
id	string	Identificador único del webhook.
userId	string	ID del usuario propietario del webhook.
url	string	La URL del endpoint registrado.
events	string[]	Eventos a los que el webhook está suscrito.
active	boolean	Si el webhook está activo. Siempre true para un webhook recién creado.
createdAt	string	Marca de tiempo ISO 8601 de cuándo se creó el webhook.

Ejemplo

{
  "data": {
    "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "webhook": {
      "id": "webhook-abc123def456",
      "userId": "uid_a1b2c3d4e5f6",
      "url": "https://your-app.com/webhooks/docmap",
      "events": ["extraction.completed", "extraction.failed"],
      "active": true,
      "createdAt": "2025-01-15T10:00:00.000Z"
    }
  }
}

Errores

Estado	Código	Descripción
400	MAX_WEBHOOKS_REACHED	Has alcanzado el máximo de 10 webhooks activos. Elimina un webhook existente antes de crear uno nuevo.
401	UNAUTHORIZED	Clave API / token faltante, inválido o expirado.