Referencia de la API: webhooks

Los webhooks salientes notifican a sus sistemas cuando se producen eventos en ProcessMind. Cada envío es una solicitud JSON POST firmada con el secreto del webhook: el encabezado X-ProcessMind-Signature contiene sha256=<hex>, un HMAC-SHA256 del cuerpo sin procesar de la solicitud. Verifique la firma con los bytes exactos que recibió (antes de analizar el JSON) y rechace los envíos cuya firma no coincida. Cada cuerpo también incluye un deliveryId, que puede usar para eliminar duplicados en los envíos con entrega al menos una vez.

Listar los webhooks salientes

Endpoint: GET /v1/tenant/{tenantId}/webhooks

Autenticación: Clave de API con alcance de Tenant · alcance read

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid
limit	integer	consulta	No	Número máximo de elementos que se devolverán
offset	integer	consulta	No	Número de elementos que se omitirán

Respuesta (200):

Lista de webhooks

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"url": "string",
		"events": [
			"process.created"
		],
		"description": "string",
		"isActive": true,
		"createdAt": "2024-03-15T16:30:00Z"
	}
]

Errores:

• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado

Crear un webhook saliente (el secreto de firma se devuelve una sola vez)

Endpoint: POST /v1/tenant/{tenantId}/webhooks

Autenticación: Clave de API con alcance de Tenant · alcance write

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid

Cuerpo de la solicitud:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string"
}

Campo	Tipo	Obligatorio	Descripción
url	string	Sí	Endpoint https público que recibe los envíos POST firmados (no se admiten direcciones privadas ni de loopback)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sí	Eventos que activan un envío a este webhook
description	string	No	Descripción opcional Longitud máxima: 500

Respuesta (201):

Webhook creado (incluye el secreto de firma)

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"secret": "string"
}

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Formato: uuid
url	string	Sí	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sí
description	string	Sí	Longitud máxima: 500
isActive	boolean	Sí	Valor predeterminado: true
createdAt	string	Sí	Formato: date-time
secret	string	Sí	Secreto de firma; solo se devuelve aquí, al crear el webhook

Errores:

• 400 Solicitud incorrecta: por ejemplo, una expresión de filtro no válida, un proceso sin modelo, un tipo de archivo no admitido o un campo obligatorio ausente
• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado

Consultar un webhook saliente

Endpoint: GET /v1/tenant/{tenantId}/webhooks/{webhookId}

Autenticación: Clave de API con alcance de Tenant · alcance read

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid
webhookId	string	ruta	Sí	Formato: uuid

Respuesta (200):

Webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Formato: uuid
url	string	Sí	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sí
description	string	Sí	Longitud máxima: 500
isActive	boolean	Sí	Valor predeterminado: true
createdAt	string	Sí	Formato: date-time

Errores:

• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado
• 404 No se encontró el recurso

Actualizar un webhook saliente

Endpoint: PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

Autenticación: Clave de API con alcance de Tenant · alcance write

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid
webhookId	string	ruta	Sí	Formato: uuid

Cuerpo de la solicitud:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true
}

Campo	Tipo	Obligatorio	Descripción
url	string	No	Endpoint https público que recibe los envíos POST firmados
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	No	Eventos que activan un envío a este webhook
description	string	No	Descripción opcional Longitud máxima: 500
isActive	boolean	No	Indica si el webhook está habilitado

Respuesta (200):

Webhook actualizado

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	Formato: uuid
url	string	Sí	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sí
description	string	Sí	Longitud máxima: 500
isActive	boolean	Sí	Valor predeterminado: true
createdAt	string	Sí	Formato: date-time

Errores:

• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado
• 404 No se encontró el recurso

Eliminar un webhook saliente

Endpoint: DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

Autenticación: Clave de API con alcance de Tenant · alcance write

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid
webhookId	string	ruta	Sí	Formato: uuid

Respuesta (200):

Webhook eliminado

{
	"deleted": true
}

Campo	Tipo	Obligatorio	Descripción
deleted	boolean	Sí

Errores:

• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado
• 404 No se encontró el recurso

Enviar una prueba al webhook

Endpoint: POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

Autenticación: Clave de API con alcance de Tenant · alcance write

Parámetros:

Nombre	Tipo	Ubicación	Obligatorio	Descripción
tenantId	string	ruta	Sí	Formato: uuid
webhookId	string	ruta	Sí	Formato: uuid

Respuesta (200):

Prueba enviada

{
	"message": "string"
}

Campo	Tipo	Obligatorio	Descripción
message	string	Sí

Errores:

• 401 Falta la Clave de API, no es válida, está deshabilitada o ha caducado
• 404 No se encontró el recurso