API-Referenz: Webhooks

Ausgehende Webhooks benachrichtigen Ihre Systeme, wenn in ProcessMind Ereignisse auftreten. Jede Zustellung erfolgt als signierter JSON-POST. Der Header X-ProcessMind-Signature enthält sha256=<hex>, einen HMAC-SHA256-Hash des unveränderten Anforderungstexts. Prüfen Sie die Signatur anhand der exakt empfangenen Bytes, bevor Sie das JSON verarbeiten, und weisen Sie Zustellungen mit ungültiger Signatur zurück. Jeder Anforderungstext enthält außerdem eine deliveryId, mit der Sie Mehrfachzustellungen erkennen können.

Ausgehende Webhooks auflisten

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

Authentifizierung: Mandantenbezogener API-Schlüssel · read Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid
limit	Ganzzahl	Abfrage	Nein	Maximale Anzahl der zurückzugebenden Einträge
offset	Ganzzahl	Abfrage	Nein	Anzahl der zu überspringenden Einträge

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 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen

Ausgehenden Webhook erstellen (Signaturgeheimnis wird einmalig zurückgegeben)

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid

Anforderungstext:

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

Feld	Typ	Erforderlich	Beschreibung
url	Zeichenfolge	Ja	Öffentlicher HTTPS-Endpunkt, der signierte POST-Zustellungen empfängt (keine privaten Adressen 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	Zeichenfolge	Nein	Optionale Beschreibung Maximale Länge: 500

Antwort (201):

Webhook erstellt (enthält das Signaturgeheimnis)

{
	"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	Zeichenfolge	Ja	Format: uuid
url	Zeichenfolge	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	Zeichenfolge	Ja	Maximale Länge: 500
isActive	boolesch	Ja	Standard: true
createdAt	Zeichenfolge	Ja	Format: date-time
secret	Zeichenfolge	Ja	Signaturgeheimnis; wird nur hier bei der Erstellung zurückgegeben

Fehler:

• 400 Ungültige Anfrage, zum Beispiel durch einen ungültigen Filterausdruck, einen Prozess ohne Modell, einen nicht unterstützten Upload-Typ oder ein fehlendes Pflichtfeld
• 401 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen

Einzelnen ausgehenden Webhook abrufen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · read Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid
webhookId	Zeichenfolge	Pfad	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	Zeichenfolge	Ja	Format: uuid
url	Zeichenfolge	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	Zeichenfolge	Ja	Maximale Länge: 500
isActive	boolesch	Ja	Standard: true
createdAt	Zeichenfolge	Ja	Format: date-time

Fehler:

• 401 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen
• 404 Ressource nicht gefunden

Ausgehenden Webhook aktualisieren

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid
webhookId	Zeichenfolge	Pfad	Ja	Format: uuid

Anforderungstext:

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

Feld	Typ	Erforderlich	Beschreibung
url	Zeichenfolge	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	Zeichenfolge	Nein	Optionale Beschreibung Maximale Länge: 500
isActive	boolesch	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	Zeichenfolge	Ja	Format: uuid
url	Zeichenfolge	Ja	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Ja
description	Zeichenfolge	Ja	Maximale Länge: 500
isActive	boolesch	Ja	Standard: true
createdAt	Zeichenfolge	Ja	Format: date-time

Fehler:

• 401 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen
• 404 Ressource nicht gefunden

Ausgehenden Webhook löschen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid
webhookId	Zeichenfolge	Pfad	Ja	Format: uuid

Antwort (200):

Webhook gelöscht

{
	"deleted": true
}

Feld	Typ	Erforderlich	Beschreibung
deleted	boolesch	Ja

Fehler:

• 401 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen
• 404 Ressource nicht gefunden

Testzustellung an den Webhook auslösen

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

Authentifizierung: Mandantenbezogener API-Schlüssel · write Geltungsbereich

Parameter:

Name	Typ	Speicherort	Erforderlich	Beschreibung
tenantId	Zeichenfolge	Pfad	Ja	Format: uuid
webhookId	Zeichenfolge	Pfad	Ja	Format: uuid

Antwort (200):

Testzustellung ausgelöst

{
	"message": "string"
}

Feld	Typ	Erforderlich	Beschreibung
message	Zeichenfolge	Ja

Fehler:

• 401 API-Schlüssel fehlt, ist ungültig, deaktiviert oder abgelaufen
• 404 Ressource nicht gefunden