Referência da API: Webhooks

Webhooks de saída notificam seus próprios sistemas quando eventos acontecem dentro do ProcessMind. Cada entrega é um POST JSON assinado com o segredo do seu Webhook: o cabeçalho X-ProcessMind-Signature contém sha256=<hex>, um HMAC-SHA256 do corpo bruto da solicitação. Verifique a assinatura comparando-a com os bytes exatos recebidos, antes de analisar o JSON, e rejeite as entregas cuja assinatura não corresponda. Cada corpo também contém um deliveryId, que você pode usar para eliminar duplicidades em entregas de pelo menos uma vez.

Listar Webhooks de saída

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

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

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 um Webhook de saída (retorna o segredo de assinatura uma única vez)

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

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

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 público https que recebe entregas POST assinadas, sem 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, incluindo 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 somente aqui, no momento da criação

Erros:

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

Obter um único Webhook de saída

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

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

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 específica do 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 público https 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á habilitado

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 específica do 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 específica do 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