Referência da API: webhooks

Os webhooks de saída notificam seus sistemas quando ocorrem eventos no ProcessMind. Cada entrega é uma solicitação JSON POST assinada com o segredo do webhook: o cabeçalho X-ProcessMind-Signature contém sha256=<hex>, um HMAC-SHA256 do corpo original da solicitação. Verifique a assinatura usando exatamente os bytes recebidos, antes de analisar o JSON, e rejeite entregas cuja assinatura não corresponda. Cada corpo também inclui um deliveryId, que você pode usar para eliminar duplicatas em entregas que podem ser repetidas.

Listar webhooks de saída

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

Autenticação: Chave de API com escopo de ambiente · escopo read

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid
limit	integer	consulta	Não	Número máximo de itens a retornar
offset	integer	consulta	Não	Número de itens a ignorar

Resposta (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"
	}
]

Erros:

• 401 Chave de API ausente, inválida, desativada ou expirada

Criar webhook de saída (o segredo de assinatura é retornado uma única vez)

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

Autenticação: Chave de API com escopo de ambiente · escopo write

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid

Corpo da solicitação:

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

Campo	Tipo	Obrigatório	Descrição
url	string	Sim	Endpoint https público que recebe entregas POST assinadas (não são aceitos endereços privados ou de loopback)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sim	Eventos que acionam uma entrega para este webhook
description	string	Não	Descrição opcional Comprimento máximo: 500

Resposta (201):

Webhook criado (inclui o segredo de assinatura)

{
	"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	Obrigatório	Descrição
id	string	Sim	Formato: uuid
url	string	Sim	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sim
description	string	Sim	Comprimento máximo: 500
isActive	boolean	Sim	Padrão: true
createdAt	string	Sim	Formato: date-time
secret	string	Sim	Segredo de assinatura; retornado apenas aqui, durante a criação

Erros:

• 400 Solicitação inválida: por exemplo, uma expressão de filtro inválida, um processo sem modelo, um tipo de arquivo não aceito ou um campo obrigatório ausente
• 401 Chave de API ausente, inválida, desativada ou expirada

Consultar um webhook de saída específico

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

Autenticação: Chave de API com escopo de ambiente · escopo read

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid
webhookId	string	caminho	Sim	Formato: uuid

Resposta (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	Obrigatório	Descrição
id	string	Sim	Formato: uuid
url	string	Sim	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sim
description	string	Sim	Comprimento máximo: 500
isActive	boolean	Sim	Padrão: true
createdAt	string	Sim	Formato: date-time

Erros:

• 401 Chave de API ausente, inválida, desativada ou expirada
• 404 Recurso não encontrado

Atualizar um webhook de saída

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

Autenticação: Chave de API com escopo de ambiente · escopo write

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid
webhookId	string	caminho	Sim	Formato: uuid

Corpo da solicitação:

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

Campo	Tipo	Obrigatório	Descrição
url	string	Não	Endpoint https público que recebe entregas POST assinadas
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Não	Eventos que acionam uma entrega para este webhook
description	string	Não	Descrição opcional Comprimento máximo: 500
isActive	boolean	Não	Indica se o webhook está ativado

Resposta (200):

Webhook atualizado

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

Campo	Tipo	Obrigatório	Descrição
id	string	Sim	Formato: uuid
url	string	Sim	Formato: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sim
description	string	Sim	Comprimento máximo: 500
isActive	boolean	Sim	Padrão: true
createdAt	string	Sim	Formato: date-time

Erros:

• 401 Chave de API ausente, inválida, desativada ou expirada
• 404 Recurso não encontrado

Excluir um webhook de saída

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

Autenticação: Chave de API com escopo de ambiente · escopo write

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid
webhookId	string	caminho	Sim	Formato: uuid

Resposta (200):

Webhook excluído

{
	"deleted": true
}

Campo	Tipo	Obrigatório	Descrição
deleted	boolean	Sim

Erros:

• 401 Chave de API ausente, inválida, desativada ou expirada
• 404 Recurso não encontrado

Acionar uma entrega de teste para o webhook

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

Autenticação: Chave de API com escopo de ambiente · escopo write

Parâmetros:

Nome	Tipo	Localização	Obrigatório	Descrição
tenantId	string	caminho	Sim	Formato: uuid
webhookId	string	caminho	Sim	Formato: uuid

Resposta (200):

Entrega de teste acionada

{
	"message": "string"
}

Campo	Tipo	Obrigatório	Descrição
message	string	Sim

Erros:

• 401 Chave de API ausente, inválida, desativada ou expirada
• 404 Recurso não encontrado