Dokumentacja API: webhooki

Wychodzące webhooki powiadamiają Państwa systemy o zdarzeniach w ProcessMind. Każde powiadomienie jest wysyłane jako żądanie JSON POST podpisane tajnym kluczem webhooka. Nagłówek X-ProcessMind-Signature zawiera sha256=<hex>, czyli HMAC-SHA256 surowej treści żądania. Podpis należy zweryfikować na podstawie dokładnie odebranych bajtów, przed przetworzeniem JSON, a powiadomienia z niezgodnym podpisem odrzucić. Każda treść zawiera też deliveryId, który pozwala usuwać duplikaty, ponieważ dostarczenie może nastąpić więcej niż raz.

Wyświetl wychodzące webhooki

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

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres read

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid
limit	integer	zapytanie	Nie	Maksymalna liczba zwracanych elementów
offset	integer	zapytanie	Nie	Liczba pomijanych elementów

Odpowiedź (200):

Lista webhooków

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

Błędy:

• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API

Utwórz wychodzący webhook (tajny klucz do podpisywania jest zwracany tylko raz)

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

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres write

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid

Treść żądania:

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

Pole	Typ	Wymagane	Opis
url	string	Tak	Publiczny endpoint https odbierający podpisane żądania POST (adresy prywatne i loopback są niedozwolone)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Tak	Zdarzenia, które uruchamiają wysłanie powiadomienia przez ten webhook
description	string	Nie	Opcjonalny opis Maksymalna długość: 500

Odpowiedź (201):

Utworzono webhook (odpowiedź zawiera tajny klucz do podpisywania)

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

Pole	Typ	Wymagane	Opis
id	string	Tak	Format: uuid
url	string	Tak	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Tak
description	string	Tak	Maksymalna długość: 500
isActive	boolean	Tak	Wartość domyślna: true
createdAt	string	Tak	Format: date-time
secret	string	Tak	Tajny klucz do podpisywania; zwracany tylko tutaj, podczas tworzenia

Błędy:

• 400 Nieprawidłowe żądanie, np. nieprawidłowe wyrażenie filtra, proces bez modelu, nieobsługiwany typ przesyłanego pliku lub brak wymaganego pola
• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API

Pobieranie pojedynczego webhooka wychodzącego

Punkt końcowy: GET /v1/tenant/{tenantId}/webhooks/{webhookId}

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres read

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid
webhookId	string	ścieżka	Tak	Format: uuid

Odpowiedź (200):

Webhook

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

Pole	Typ	Wymagane	Opis
id	string	Tak	Format: uuid
url	string	Tak	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Tak
description	string	Tak	Maksymalna długość: 500
isActive	boolean	Tak	Wartość domyślna: true
createdAt	string	Tak	Format: date-time

Błędy:

• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API
• 404 Nie znaleziono zasobu

Aktualizowanie webhooka wychodzącego

Punkt końcowy: PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres write

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid
webhookId	string	ścieżka	Tak	Format: uuid

Treść żądania:

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

Pole	Typ	Wymagane	Opis
url	string	Nie	Publiczny punkt końcowy HTTPS, który odbiera podpisane żądania POST
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Nie	Zdarzenia, które wywołują wysłanie danych do tego webhooka
description	string	Nie	Opcjonalny opis Maksymalna długość: 500
isActive	boolean	Nie	Określa, czy webhook jest włączony

Odpowiedź (200):

Zaktualizowany webhook

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

Pole	Typ	Wymagane	Opis
id	string	Tak	Format: uuid
url	string	Tak	Format: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	Tak
description	string	Tak	Maksymalna długość: 500
isActive	boolean	Tak	Wartość domyślna: true
createdAt	string	Tak	Format: date-time

Błędy:

• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API
• 404 Nie znaleziono zasobu

Usuwanie webhooka wychodzącego

Punkt końcowy: DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres write

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid
webhookId	string	ścieżka	Tak	Format: uuid

Odpowiedź (200):

Webhook usunięty

{
	"deleted": true
}

Pole	Typ	Wymagane	Opis
deleted	boolean	Tak

Błędy:

• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API
• 404 Nie znaleziono zasobu

Wywołanie testowego wysłania danych do webhooka

Punkt końcowy: POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

Uwierzytelnianie: Klucz API przypisany do tenanta · zakres write

Parametry:

Nazwa	Typ	Lokalizacja	Wymagane	Opis
tenantId	string	ścieżka	Tak	Format: uuid
webhookId	string	ścieżka	Tak	Format: uuid

Odpowiedź (200):

Wywołano testowe wysłanie danych

{
	"message": "string"
}

Pole	Typ	Wymagane	Opis
message	string	Tak

Błędy:

• 401 Brakujący, nieprawidłowy, wyłączony lub wygasły klucz API
• 404 Nie znaleziono zasobu