Riferimento API: Webhook

I webhook in uscita notificano i Suoi sistemi quando si verificano eventi all’interno di ProcessMind. Ogni consegna è una richiesta POST JSON firmata con il segreto del webhook: l’intestazione X-ProcessMind-Signature contiene sha256=<hex>, un HMAC-SHA256 del corpo grezzo della richiesta. Verifichi la firma rispetto ai byte esatti ricevuti, prima di analizzare il JSON, e rifiuti le consegne la cui firma non corrisponde. Ogni corpo contiene anche un deliveryId, che può utilizzare per deduplicare le consegne effettuate almeno una volta.

Elencare i webhook in uscita

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

Autenticazione: Chiave API con ambito tenant · read ambito

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, con restituzione una tantum del segreto di firma

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

Autenticazione: Chiave API con ambito tenant · write ambito

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 pubblico https che riceve consegne POST firmate, senza indirizzi privati o di loopback
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Sì	Eventi che attivano una consegna a questo webhook
description	string	No	Descrizione facoltativa Lunghezza massima: 500

Risposta (201):

Webhook creato, incluso 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 qui, al momento della creazione

Errori:

• 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo 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 · read ambito

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	percorso	Sì	Formato: uuid
webhookId	string	percorso	Sì	Formato: uuid

Corpo della richiesta:

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

Campo	Tipo	Obbligatorio	Descrizione
url	string	No	Endpoint pubblico https che riceve le chiamate POST firmate
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	No	Eventi che attivano una chiamata 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ì	Valore 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	percorso	Sì	Formato: uuid
webhookId	string	percorso	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

Attivare una chiamata di test 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	percorso	Sì	Formato: uuid
webhookId	string	percorso	Sì	Formato: uuid

Risposta (200):

Chiamata di test attivata

{
	"message": "string"
}

Campo	Tipo	Obbligatorio	Descrizione
message	string	Sì

Errori:

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