API-Referenz: Webhooks

Ausgehende Webhooks benachrichtigen Ihre eigenen Systeme, wenn innerhalb von ProcessMind Ereignisse eintreten. Jede Zustellung ist ein mit Ihrem Webhook-Geheimnis signierter JSON-POST: Der Header X-ProcessMind-Signature enthält sha256=<hex>, einen HMAC-SHA256-Hash des unveränderten Anfragetexts. Prüfen Sie die Signatur anhand der exakt empfangenen Bytes, bevor Sie das JSON analysieren, und weisen Sie Zustellungen zurück, deren Signatur nicht übereinstimmt. Jeder Anfragetext enthält außerdem eine deliveryId, mit der Sie Zustellungen mit mindestens einmaliger Zustellung deduplizieren können.

Ausgehende Webhooks auflisten

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

Authentifizierung: Mandantenbezogener API-Schlüssel · read Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid
limit	integer	query	Nein	Maximale Anzahl zurückzugebender Elemente
offset	integer	query	Nein	Anzahl zu überspringender Elemente

Antwort (200):

Webhook-Liste

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

Fehler:

• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel

Ausgehenden Webhook erstellen (gibt das Signaturgeheimnis einmalig zurück)

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid

Anfragetext:

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

Feld	Typ	Erforderlich	Beschreibung
url	string	Ja	Öffentlicher HTTPS-Endpunkt, der signierte POST-Zustellungen empfängt, keine privaten oder Loopback-Adressen
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja	Ereignisse, die eine Zustellung an diesen Webhook auslösen
description	string	Nein	Optionale Beschreibung Maximale Länge: 500

Antwort (201):

Webhook erstellt, einschließlich des Signaturgeheimnisses

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

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Format: uuid
url	string	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale Länge: 500
isActive	boolean	Ja	Standard: true
createdAt	string	Ja	Format: date-time
secret	string	Ja	Signaturgeheimnis, nur hier bei der Erstellung zurückgegeben

Fehler:

• 400 Ungültige Anfrage, z. B. ein ungültiger Filterausdruck, ein Prozess ohne Modell, ein nicht unterstützter Upload-Typ oder ein fehlendes Pflichtfeld
• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel

Einzelnen ausgehenden Webhook abrufen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · read Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid
webhookId	string	path	Ja	Format: uuid

Antwort (200):

Webhook

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

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Format: uuid
url	string	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale Länge: 500
isActive	boolean	Ja	Standard: true
createdAt	string	Ja	Format: date-time

Fehler:

• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel
• 404 Ressource nicht gefunden

Ausgehenden Webhook aktualisieren

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write-Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid
webhookId	string	path	Ja	Format: uuid

Anfragetext:

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

Feld	Typ	Erforderlich	Beschreibung
url	string	Nein	Öffentlicher HTTPS-Endpunkt, der signierte POST-Zustellungen empfängt
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Nein	Ereignisse, die eine Zustellung an diesen Webhook auslösen
description	string	Nein	Optionale Beschreibung Maximale Länge: 500
isActive	boolean	Nein	Gibt an, ob der Webhook aktiviert ist

Antwort (200):

Webhook aktualisiert

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

Feld	Typ	Erforderlich	Beschreibung
id	string	Ja	Format: uuid
url	string	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	string	Ja	Maximale Länge: 500
isActive	boolean	Ja	Standard: true
createdAt	string	Ja	Format: date-time

Fehler:

• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel
• 404 Ressource nicht gefunden

Ausgehenden Webhook löschen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write-Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid
webhookId	string	path	Ja	Format: uuid

Antwort (200):

Webhook gelöscht

{
	"deleted": true
}

Feld	Typ	Erforderlich	Beschreibung
deleted	boolean	Ja

Fehler:

• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel
• 404 Ressource nicht gefunden

Testzustellung an den Webhook auslösen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write-Bereich

Parameter:

Name	Typ	Ort	Erforderlich	Beschreibung
tenantId	string	path	Ja	Format: uuid
webhookId	string	path	Ja	Format: uuid

Antwort (200):

Testzustellung ausgelöst

{
	"message": "string"
}

Feld	Typ	Erforderlich	Beschreibung
message	string	Ja

Fehler:

• 401 Fehlender, ungültiger, deaktivierter oder abgelaufener API-Schlüssel
• 404 Ressource nicht gefunden