API-referentie: Webhooks

Uitgaande webhooks sturen een melding naar je eigen systemen wanneer er iets gebeurt in ProcessMind. Elke melding wordt verstuurd als een JSON POST en ondertekend met het webhookgeheim: de header X-ProcessMind-Signature bevat sha256=<hex>, een HMAC-SHA256 van de onbewerkte requestbody. Controleer de handtekening aan de hand van exact de bytes die je hebt ontvangen, voordat je de JSON verwerkt. Wijs meldingen af als de handtekening niet overeenkomt. Elke body bevat ook een deliveryId, waarmee je dubbele meldingen kunt voorkomen wanneer een melding meerdere keren wordt afgeleverd.

Uitgaande webhooks weergeven

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

Authenticatie: API-sleutel voor Tenant · read-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Formaat: uuid
limit	integer	query	Nee	Maximumaantal items in het antwoord
offset	integer	query	Nee	Aantal items dat wordt overgeslagen

Antwoord (200):

Lijst met webhooks

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

Fouten:

• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen

Een uitgaande webhook aanmaken (het ondertekeningsgeheim wordt één keer teruggegeven)

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

Authenticatie: API-sleutel voor Tenant · write-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Formaat: uuid

Request body:

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

Veld	Type	Verplicht	Beschrijving
url	string	Ja	Openbaar https-endpoint dat ondertekende POST-meldingen ontvangt (geen privé- of loopbackadressen)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja	Gebeurtenissen die een melding naar deze webhook versturen
description	string	Nee	Optionele beschrijving Maximale lengte: 500

Antwoord (201):

Webhook aangemaakt (bevat het ondertekeningsgeheim)

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

Veld	Type	Verplicht	Beschrijving
id	string	Ja	Formaat: uuid
url	string	Ja	Formaat: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale lengte: 500
isActive	boolean	Ja	Standaard: true
createdAt	string	Ja	Formaat: date-time
secret	string	Ja	Ondertekeningsgeheim; wordt alleen hier, bij het aanmaken, teruggegeven

Fouten:

• 400 Ongeldig verzoek: bijvoorbeeld een ongeldige filterexpressie, een proces zonder model, een niet-ondersteund uploadtype of een verplicht veld dat ontbreekt
• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen

Een uitgaande webhook ophalen

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

Authenticatie: API-sleutel voor Tenant · read-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Formaat: uuid
webhookId	string	pad	Ja	Formaat: uuid

Antwoord (200):

Webhook

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

Veld	Type	Verplicht	Beschrijving
id	string	Ja	Indeling: uuid
url	string	Ja	Indeling: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale lengte: 500
isActive	boolean	Ja	Standaard: true
createdAt	string	Ja	Indeling: date-time

Fouten:

• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen
• 404 Bron niet gevonden

Een uitgaande webhook bijwerken

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

Authenticatie: API-sleutel voor tenant · write-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Indeling: uuid
webhookId	string	pad	Ja	Indeling: uuid

Requestbody:

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

Veld	Type	Verplicht	Beschrijving
url	string	Nee	Openbaar https-eindpunt dat ondertekende POST-verzoeken ontvangt
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Nee	Gebeurtenissen die een verzending naar deze webhook activeren
description	string	Nee	Optionele beschrijving Maximale lengte: 500
isActive	boolean	Nee	Of de webhook is ingeschakeld

Antwoord (200):

Webhook bijgewerkt

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

Veld	Type	Verplicht	Beschrijving
id	string	Ja	Indeling: uuid
url	string	Ja	Indeling: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale lengte: 500
isActive	boolean	Ja	Standaard: true
createdAt	string	Ja	Indeling: date-time

Fouten:

• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen
• 404 Bron niet gevonden

Een uitgaande webhook verwijderen

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

Authenticatie: API-sleutel voor tenant · write-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Indeling: uuid
webhookId	string	pad	Ja	Indeling: uuid

Antwoord (200):

Webhook verwijderd

{
	"deleted": true
}

Veld	Type	Verplicht	Beschrijving
deleted	boolean	Ja

Fouten:

• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen
• 404 Bron niet gevonden

Een testverzending naar de webhook starten

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

Authenticatie: API-sleutel voor tenant · write-scope

Parameters:

Naam	Type	Locatie	Verplicht	Beschrijving
tenantId	string	pad	Ja	Indeling: uuid
webhookId	string	pad	Ja	Indeling: uuid

Antwoord (200):

Testverzending gestart

{
	"message": "string"
}

Veld	Type	Verplicht	Beschrijving
message	string	Ja

Fouten:

• 401 API-sleutel ontbreekt, is ongeldig, uitgeschakeld of verlopen
• 404 Bron niet gevonden