Documentazione API: webhook

I webhook in uscita notificano i Suoi sistemi quando si verificano eventi in ProcessMind. Ogni notifica viene inviata con una richiesta JSON POST firmata con il segreto del webhook: l’intestazione X-ProcessMind-Signature contiene sha256=<hex>, un HMAC-SHA256 del corpo originale della richiesta. Verifichi la firma sui byte esatti ricevuti, prima di analizzare il JSON, e rifiuti le notifiche con una firma non corrispondente. Ogni corpo include anche un deliveryId, utile per eliminare i duplicati quando una notifica viene consegnata più volte.

Elencare i webhook in uscita

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

Autenticazione: Chiave API con ambito Tenant · ambito read

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
limit	integer	query	No	Numero massimo di elementi da restituire
offset	integer	query	No	Numero di elementi da ignorare

Risposta (200):

Elenco dei webhook

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

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta

Creare un webhook in uscita (il segreto di firma viene restituito una sola volta)

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

Autenticazione: Chiave API con ambito Tenant · ambito write

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid

Corpo della richiesta:

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

Campo	Tipo	Obbligatorio	Descrizione
url	string	Sì	Endpoint https pubblico che riceve le notifiche POST firmate (non sono consentiti indirizzi privati o di loopback)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sì	Eventi che attivano l’invio di una notifica a questo webhook
description	string	No	Descrizione facoltativa Lunghezza massima: 500

Risposta (201):

Webhook creato (include il segreto di 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	Obbligatorio	Descrizione
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ì	Lunghezza massima: 500
isActive	boolean	Sì	Predefinito: true
createdAt	string	Sì	Formato: date-time
secret	string	Sì	Segreto di firma, restituito solo in questa risposta alla creazione

Errori:

• 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un formato di caricamento non supportato o un campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta

Ottenere un singolo webhook in uscita

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

Autenticazione: Chiave API con ambito Tenant · ambito read

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
webhookId	string	path	Sì	Formato: uuid

Risposta (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	Obbligatorio	Descrizione
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ì	Lunghezza massima: 500
isActive	boolean	Sì	Predefinito: true
createdAt	string	Sì	Formato: date-time

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Aggiornare un webhook in uscita

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

Autenticazione: Chiave API con ambito Tenant · ambito write

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
webhookId	string	path	Sì	Formato: uuid

Corpo della richiesta:

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

Campo	Tipo	Obbligatorio	Descrizione
url	string	No	Endpoint https pubblico che riceve le notifiche POST firmate
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	No	Eventi che attivano l’invio di una notifica a questo webhook
description	string	No	Descrizione facoltativa Lunghezza massima: 500
isActive	boolean	No	Indica se il webhook è abilitato

Risposta (200):

Webhook aggiornato

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

Campo	Tipo	Obbligatorio	Descrizione
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ì	Lunghezza massima: 500
isActive	boolean	Sì	Predefinito: true
createdAt	string	Sì	Formato: date-time

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Eliminare un webhook in uscita

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

Autenticazione: Chiave API con ambito Tenant · ambito write

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
webhookId	string	path	Sì	Formato: uuid

Risposta (200):

Webhook eliminato

{
	"deleted": true
}

Campo	Tipo	Obbligatorio	Descrizione
deleted	boolean	Sì

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata

Inviare una notifica di prova al webhook

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

Autenticazione: Chiave API con ambito Tenant · ambito write

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	path	Sì	Formato: uuid
webhookId	string	path	Sì	Formato: uuid

Risposta (200):

Notifica di prova inviata

{
	"message": "string"
}

Campo	Tipo	Obbligatorio	Descrizione
message	string	Sì

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 404 Risorsa non trovata