Eigene Webhooks registrieren

Über Webhooks könnt ihr euer externes System in Echtzeit über Änderungen im Blink-System informieren lassen. Wenn ein bestimmtes Ereignis (Event) eintritt, sendet Blink automatisch eine HTTP-POST-Anfrage an eine von euch hinterlegte URL.

Die Webhook-Verwaltung erfolgt über die OData-API des Blink Automation Service unter dem Endpunkt /odata/v1/WebhookRegistrations.

Webhook registrieren

Um einen Webhook zu registrieren, sendet eine POST-Anfrage. Gebt die Ziel-URL und die gewünschten Events als Array an. Optional könnt ihr einen Filter-Ausdruck angeben, um die Events einzuschränken.

Anfrage (Curl)

Bash

curl --request POST 'https://[SYSTEM]-automation-service.blink.online/odata/v1/WebhookRegistrations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [ID_TOKEN]' \
--data-raw '{
    "Url": "https://example.com/my-webhook-endpoint",
    "Events": ["TicketCreated", "TicketUpdated"]
}'

Antwort (HTTP 201 Created)

JSON

{
    "Id": 1,
    "Url": "https://example.com/my-webhook-endpoint",
    "Filter": null,
    "Events": ["TicketCreated", "TicketUpdated"]
}

Webhook mit Filter registrieren

Über das optionale Feld Filter könnt ihr einschränken, bei welchen Event-Daten der Webhook ausgelöst wird. Ist das Feld null, wird der Webhook bei jedem Event ausgelöst.

Der Filter verwendet JsonPath-Syntax. Da JsonPath nur Listen in einem Datenobjekt filtern kann, wird das Event automatisch in ein Dummy-Objekt mit dem Listenfeld data eingebettet. Es kann nur nach Feldern gefiltert werden, die im Payload des jeweiligen Events enthalten sind (siehe Tabelle unter "Verfügbare Events").

Beispiel-Event (Payload)

JSON

{
    "Id": 1,
    "CompanyId": 4,
    "TicketTypeId": 120
}

Webhook nur für CompanyId 4 auslösen

$.data[?(@.CompanyId == 4)]

Webhook nur für CompanyId 4 oder 5 auslösen

$.data[?(@.CompanyId == 4 || @.CompanyId == 5)]

Webhook nur für CompanyId 4 und TicketTypeId 120 auslösen

$.data[?(@.CompanyId == 4 && @.TicketTypeId == 120)]

Webhook nur für CompanyId 4 oder 5 und TicketTypeId 120 auslösen

$.data[?((@.CompanyId == 4 || @.CompanyId == 5) && @.TicketTypeId == 120)]

Eigene JsonPath-Ausdrücke können unter dotnetfiddle.net/D9yclP getestet werden.

Anfrage (Curl)

Bash

curl --request POST 'https://[SYSTEM]-automation-service.blink.online/odata/v1/WebhookRegistrations' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [ID_TOKEN]' \
--data-raw '{
    "Url": "https://example.com/my-webhook-endpoint",
    "Events": ["TicketCreated"],
    "Filter": "$.data[?(@.CompanyId == 4)]"
}'

Alle Webhooks abrufen

Anfrage (Curl)

Bash

curl --request GET 'https://[SYSTEM]-automation-service.blink.online/odata/v1/WebhookRegistrations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [ID_TOKEN]'

Webhook löschen

Um einen registrierten Webhook zu löschen, sendet eine DELETE-Anfrage mit der Webhook-ID.

Anfrage (Curl)

Bash

curl --request DELETE 'https://[SYSTEM]-automation-service.blink.online/odata/v1/WebhookRegistrations(1)' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer [ID_TOKEN]'

Webhooks absichern

Webhook-Aufrufe von Blink an eure Ziel-URL erfolgen ohne Authentifizierung. Es ist nicht möglich, Authentifizierungsverfahren wie z.B. Basic Auth zu verwenden. Die ausgehenden Requests können auch nicht um eigene HTTP-Header oder zusätzliche Post-Body-Daten ergänzt werden.

Um eure Webhook-URL gegen unbefugte Aufrufe abzusichern, könnt ihr ein geheimes Token als GET-Parameter an die URL anhängen. Dieses Token wird dann bei jedem Webhook-Aufruf mitgesendet und kann von eurem Endpunkt validiert werden.

Beispiel

https://example.com/my-webhook-endpoint?token=mein-geheimes-token

Verfügbare Events

Die folgende Tabelle zeigt alle Events, die für Webhooks zur Verfügung stehen.

Event	Payload
AbsenceCreated	Id, CompanyId
AbsenceRemoved	Id, CompanyId
AbsenceUpdated	Id, CompanyId
AcknowledgementCreated	Id, CompanyId, WorkOrderId, WorkOrderItemId
AcknowledgementDeleted	Id, CompanyId, WorkOrderId, WorkOrderItemId
AreaRemoved	Id, CompanyId
BlinkAppActivated	Id
BlinkAppDeactivated	Id
CategoryCreated	Id, CompanyId
CategoryPermissionGroupAssigned	Id, CompanyId, CategoryId, PermissionGroupId
CategoryPermissionGroupRemoved	Id, CompanyId, CategoryId, PermissionGroupId
CategoryRemoved	Id, CompanyId
CategoryTranslationCreated	Id, CompanyId, CategoryId, LanguageId
CategoryTranslationDeleted	Id, CompanyId, CategoryId, LanguageId
CategoryTranslationUpdated	Id, CompanyId, CategoryId, LanguageId
CategoryUpdated	Id, CompanyId
ChecklistDataCreated	Id, ChecklistId, CompanyId
CompanyActivated	Id, CompanyId
CompanyBlinkAppActivated	Id, CompanyId, BlinkAppId
CompanyBlinkAppDeactivated	Id, CompanyId, BlinkAppId
CompanyCreated	Id, CompanyId
CompanyDeactivated	Id, CompanyId
CompanyFeatureActivated	Id, CompanyId, FeatureId
CompanyFeatureDeactivated	Id, CompanyId, FeatureId
CompanyPermissionGroupBlinkAppActivated	Id, CompanyId, PermissionGroupId, BlinkAppId
CompanyPermissionGroupBlinkAppDeactivated	Id, CompanyId, PermissionGroupId, BlinkAppId
CompanyPermissionGroupCreated	Id, CompanyId, PermissionGroupId
CompanyPermissionGroupRemoved	Id, CompanyId, PermissionGroupId
CompanyPermissionGroupUpdated	Id, CompanyId, PermissionGroupId
CompanySettingsChanged	Id, CompanyId
CompanyUpdated	Id, CompanyId
CustomerCreated	Id, CompanyId
CustomerUpdated	Id, CompanyId
EmployeeCreated	Id, CompanyId
EmployeeDeactivated	Id, CompanyId
EmployeeLoginCardConnected	Id, CompanyId, LoginCardId
EmployeeRemoved	Id, CompanyId, LoginUserId
EmployeeUpdated	Id, CompanyId
FileCategoryAssigned	Id, CompanyId, FileId, CategoryId
FileCategoryRemoved	Id, CompanyId, FileId, CategoryId
FileCreated	Id, CompanyId
FileEmployeeAssigned	Id, CompanyId, FileId, ReferenceId
FileEmployeeRemoved	Id, CompanyId, FileId, ReferenceId
FileLocationAssigned	Id, CompanyId, FileId, ReferenceId
FileLocationRemoved	Id, CompanyId, FileId, ReferenceId
FileRemoved	Id, CompanyId
FileTagAssigned	Id, CompanyId, FileId, TagId
FileTagRemoved	Id, CompanyId, FileId, TagId
FileTranslationCreated	Id, CompanyId, FileId, LanguageId
FileTranslationDeleted	Id, CompanyId, FileId, LanguageId
FileTranslationUpdated	Id, CompanyId, FileId, LanguageId
FileUpdated	Id, CompanyId
LocationActivated	Id, CompanyId
LocationCreated	Id, CompanyId
LocationDeactivated	Id, CompanyId
LocationManagerAssigned	Id, LocationManagerId, CompanyId
LocationManagerRemoved	Id, LocationManagerId, CompanyId
LocationUpdated	Id, CompanyId
LoginUserActivated	Id, CompanyId
LoginUserCreated	Id
LoginUserDeactivated	Id, CompanyId
LoginUserPermissionGroupChanged	Id, CompanyId
LoginUserRemoved	Id
LoginUserUpdated	Id, CompanyId
NewsCreated	Id, CompanyId
NewsRemoved	Id, CompanyId
NewsUpdated	Id, CompanyId
PermissionGroupCreated	Id
PermissionGroupDeleted	Id
PermissionGroupUpdated	Id
TagCreated	Id
TagRemoved	Id
TeamleaderAssigned	Id, TeamleaderId, CompanyId
TeamleaderRemoved	Id, TeamleaderId, CompanyId
TicketAssigneeChanged	Id, LoginUserIdBefore, LoginUserIdAfter, CompanyId, TicketTypeId
TicketAttachmentCreated	Id, TicketId, CompanyId, TicketTypeId
TicketAttachmentRemoved	Id, TicketId, CompanyId, TicketTypeId
TicketCommentCreated	Id, TicketId, CompanyId, TicketTypeId
TicketCommentRemoved	Id, TicketId, CompanyId, TicketTypeId
TicketCreated	Id, CompanyId, TicketTypeId
TicketRemoved	Id, CompanyId, TicketTypeId
TicketStatusCreated	Id, TicketTypeId
TicketStatusRemoved	Id, TicketTypeId
TicketStatusUpdated	Id, TicketTypeId
TicketTicketStatusChanged	Id, CompanyId, TicketStatusIdBefore, TicketStatusIdAfter, TicketTypeId
TicketTypeCreated	Id
TicketTypeRemoved	Id
TicketTypeUpdated	Id
TicketUpdated	Id, CompanyId, TicketTypeId
TicketWatcherCreated	Id, TicketId, LoginUserId, CompanyId, TicketTypeId
TicketWatcherRemoved	Id, TicketId, LoginUserId, CompanyId, TicketTypeId
TimeLimitCreated	Id, CompanyId, EmployeeId
TimeLimitRemoved	Id, CompanyId, EmployeeId
TimeLimitUpdated	Id, CompanyId, EmployeeId
WorkOrderAttachmentCreated	Id, CompanyId, WorkOrderId
WorkOrderAttachmentRemoved	Id, CompanyId, WorkOrderId
WorkOrderCommentCreated	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderCommentRemoved	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderCreated	Id, CompanyId
WorkOrderItemAttachmentCreated	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderItemAttachmentRemoved	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderItemCommentCreated	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderItemCommentRemoved	Id, CompanyId, WorkOrderId, WorkOrderItemId
WorkOrderItemCreated	Id, CompanyId, WorkOrderId
WorkOrderItemEmployeeAssigned	Id, CompanyId, WorkOrderId, WorkOrderItemId, EmployeeIdBefore
WorkOrderItemEmployeeRemoved	Id, CompanyId, WorkOrderId, WorkOrderItemId, EmployeeIdBefore
WorkOrderItemRemoved	Id, CompanyId, WorkOrderId
WorkOrderItemStatusChanged	Id, CompanyId, WorkOrderId, StatusBefore, StatusAfter
WorkOrderItemUpdated	Id, CompanyId, WorkOrderId
WorkOrderRemoved	Id, CompanyId
WorkOrderResponsibleEmployeeAssigned	Id, CompanyId, WorkOrderId, EmployeeIdBefore
WorkOrderResponsibleEmployeeRemoved	Id, CompanyId, WorkOrderId, EmployeeIdBefore
WorkOrderStatusChanged	Id, CompanyId, StatusBefore, StatusAfter
WorkOrderUpdated	Id, CompanyId