APIs zum Registrieren & Verwalten von Webhooks
/webhook
API-Endpunkt zum Verwalten von Abonnements für Ereignisse in Kaizala.
WebHooks ist ein einfaches HTTP-Muster, das ein einfaches Herausgeber-/Abonnentenmodell für die Verkabelung von Web-APIs und SaaS-Diensten bereitstellt. Wenn ein Ereignis in Kaizala auftritt, wird eine Benachrichtigung in Form einer HTTP POST-Anforderung an registrierte Abonnenten gesendet. Die POST-Anforderung enthält Informationen zum Ereignis, die es dem Empfänger ermöglicht, entsprechend zu handeln.
Mithilfe von WebHooks können Sie verschiedene Ereignisse abonnieren, die innerhalb eines Konversationsgruppenkontexts in Kaizala auftreten.
POST /webhook
POST {endpoint-url}/v1/webhook
Um sicherzustellen, dass Ihr Webhook-Dienstendpunkt authentisch ist und funktioniert, überprüfen wir Ihre Rückruf-URL vor dem Erstellen des Abonnements. Zur Überprüfung senden wir Ihnen ein Validierungstoken, das Sie uns innerhalb von 5 Sekunden zurücksenden müssen. Weitere Informationen
Anforderungsparameter
| Parameter | Typ | Optional? | Beschreibung | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| HTTP-Header | accessToken | Zeichenfolge | Nein | Zugriffstoken, das vom Authentifizierungsendpunkt empfangen wird | HTTP-Header | Content-Type | Zeichenfolge | Nein | "application/json" |
Anforderungstext
| Parameter | Typ | Optional? | Beschreibung |
|---|---|---|---|
| objectId | String | Nein | Bezeichner, der das Objekt darstellt, in dem die Webhooks erstellt werden müssen. Für ObjectType=Group, den Bezeichner der Gruppe, für ObjectType=Action, seine actionId, für ObjectType=ActionPackage, seine action-package-id |
| objectType | String | Nein | Enumeration: "Group"/"Action"/"ActionPackage" |
| eventTypes | Array | Nein | Array verschiedener Ereignistypen, die Sie für den Webhook abonnieren müssen. Unterstützte Ereignisse sind: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | Zeichenfolge | Nein | HTTPS-URL, an die die abonnierten Ereignisse benachrichtigt werden müssen |
| callBackToken | Zeichenfolge | Ja | Optionaler Parameter, den Sie festlegen können, der im HTTP-Header "kz-callback-token" mit jedem vom WebHook durchgeführten CallBack gesendet wird |
| callBackContext | Zeichenfolge | Ja | Optionaler Parameter, den Sie festlegen können, der in der JSON-Nutzlast mit jedem vom WebHook ausgeführten CallBack als "Context" gesendet wird |
| Gültigkeit | Zeichenfolge | Ja | Gültigkeit, damit der WebHook im EPOCH-Format aktiv ist. Der Standardwert ist 2 Jahre. |
Antworttext
| Parameter | Typ | Beschreibung |
|---|---|---|
| webhookId | Zeichenfolge | Bezeichner, der den erstellten WebHook darstellt |
Anforderungstext: Abonnieren aller Ereignisse auf Gruppenebene
{
"objectId":"74943849802190eaea3810",
"objectType":"Group",
"eventTypes":[
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"callBackUrl":"https://requestb.in/123",
"callBackToken":"tokenToBeVerifiedByCallback",
"callBackContext":"Any data which is required to be returned in callback"
}
Das Webhook-Antwortschema für registrierte Ereignisse in Kaizala finden Sie hier.
Hinweis: Kaizala garantiert mindestens einmal die Zustellung der Webhookantwort. In bestimmten Fällen kann es vorkommen, dass Kaizala doppelte Webhookantworten für dasselbe Ereignis sendet.
Abrufen von /webhook
GET {endpoint-url}/v1/webhook
Anforderungsparameter
| Parameter | Typ | Optional? | Beschreibung | |
|---|---|---|---|---|
| HTTP-Header | accessToken | Zeichenfolge | Nein | Zugriffstoken, das vom Authentifizierungsendpunkt empfangen wird |
| Abfrageparameter | objectId | String | Nein | Bezeichner, der das Objekt darstellt, in dem die Webhooks erstellt werden müssen. Für ObjectType=Group, den Bezeichner der Gruppe, für ObjectType=Action, seine actionId, für ObjectType=ActionPackage, seine action-package-id |
| Abfrageparameter | objectType | String | Nein | Enumeration: "Group"/"Action"/"ActionPackage" |
Antworttext
| Parameter | Typ | Beschreibung |
|---|---|---|
| Webhooks | JSON-Objektarray | Array von Webhooks, die für die objectId abonniert wurden |
JSON-Struktur für jeden einzelnen Webhook in den Array-Webhooks[]:
| Parameter | Typ | Beschreibung |
|---|---|---|
| id | Zeichenfolge | Webhookbezeichner |
| objectId | Zeichenfolge | Objektbezeichner |
| objectType | Zeichenfolge | Enumeration: "Group"/"Action"/"ActionPackage" |
| events | String[] | Ereignisliste mit jedem Wert als "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved", "GroupRemoved" |
| callBackUrl | Zeichenfolge | Rückruf-URL, an die die abonnierten Ereignisse benachrichtigt werden müssen |
| callBackToken | Zeichenfolge | Parameter, der im HTTP-Header "kz-callback-token" mit jedem vom WebHook durchgeführten CallBack gesendet wird |
| callBackContext | Zeichenfolge | Parameter, der in der JSON-Nutzlast als "Kontext" gesendet wird, bei jedem CallBack, der vom WebHook ausgeführt wird |
| Gültigkeit | Zeichenfolge | Gültigkeit, damit der WebHook im EPOCH-Format aktiv ist. |
| aktiv | Boolesch | True, wenn der Status des Webhooks aktiv ist |
JSON-Beispielantwort
{
"webhooks": [
{
"id": "dac6fccf-f2e9-4abc-94d7-793037e99da7",
"objectId": "b21405d1-4b10-4c46-bfa9-8338592f3782",
"objectType": "Group",
"events": [
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"filters": [],
"callbackUrl": "https://requestb.in/12786un1",
"callbackToken": "tokenToBeVerifiedByCallback",
"ts": 1505491564677,
"validity": 1568605416677
"active": true
}
]
}
Löschen von /webhook
DELETE {endpoint-url}/v1/webhook
Anforderungsparameter
| Parameter | Typ | Optional? | Beschreibung | |
|---|---|---|---|---|
| HTTP-Header | accessToken | Zeichenfolge | Nein | Zugriffstoken, das vom Authentifizierungsendpunkt empfangen wird |
| Path-Parameter | webhookId | Zeichenfolge | Nein | Webhookbezeichner |
PUT /webhook
PUT {endpoint-url}/v1/webhook/{webhookId}
Jeder Parameter für den Webhook kann aktualisiert werden. Der Anforderungstext kann je nach Bedarf 1 oder mehr Parameter enthalten.
Anforderungsparameter
| Parameter | Typ | Optional? | Beschreibung | |
|---|---|---|---|---|
| HTTP-Header | accessToken | Zeichenfolge | Nein | Zugriffstoken, das vom Authentifizierungsendpunkt empfangen wird |
| Path-Parameter | webhookId | Zeichenfolge | Nein | Webhookbezeichner |
Anforderungstext
| Parameter | Typ | Optional? | Beschreibung |
|---|---|---|---|
| objectId | String | Ja | Bezeichner, der das Objekt darstellt, in dem die Webhooks erstellt werden müssen. Für ObjectType=Group, den Bezeichner der Gruppe, für ObjectType=Action, seine actionId, für ObjectType=ActionPackage, seine action-package-id |
| objectType | String | Ja | Enumeration: "Group"/"Action"/"ActionPackage" |
| eventTypes | Array | Ja | Array verschiedener Ereignistypen, die Sie für den Webhook abonnieren müssen. Unterstützte Ereignisse sind: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | Zeichenfolge | Ja | HTTPS-URL, an die die abonnierten Ereignisse benachrichtigt werden müssen |
| callBackToken | Zeichenfolge | Ja | Optionaler Parameter, den Sie festlegen können, der im HTTP-Header "kz-callback-token" mit jedem vom WebHook durchgeführten CallBack gesendet wird |
| callBackContext | Zeichenfolge | Ja | Optionaler Parameter, den Sie festlegen können, der in der JSON-Nutzlast mit jedem vom WebHook ausgeführten CallBack als "Context" gesendet wird |
| Gültigkeit | Zeichenfolge | Ja | Gültigkeit, damit der WebHook im EPOCH-Format aktiv ist. Der Standardwert ist 2 Jahre. |
| Aktiv | Boolesch | Ja | Ändern Sie den Status des Webhooks in Aktiv, wenn der Wert true ist. |
Beispiel für den Inhalt der Anforderung
{
"objectId":"74943849802190eaea3810",
"objectType":"Group",
"eventTypes":[
"ActionCreated",
"ActionResponse",
"SurveyCreated",
"JobCreated",
"SurveyResponse",
"JobResponse",
"TextMessageCreated",
"AttachmentCreated",
"Announcement",
"MemberAdded",
"MemberRemoved",
"GroupAdded",
"GroupRemoved"
],
"callBackUrl":"https://requestb.in/123",
"callBackToken":"tokenToBeVerifiedByCallback",
"Active": "true"
}
Automatisches Deaktivieren von Webhooks
Um die Zuverlässigkeit unserer Webhooks zu verbessern, haben wir kürzlich die Wiederholungs- und Deaktivierungslogik hinzugefügt. Wenn die Rückruf-URL/der Endpunkt bei einem Webhook nicht erreichbar ist oder nicht mit einem anderen status Code als 2xx (>=3xx) antwortet, versucht unser Dienst, ihn innerhalb von 2 Tagen 6-mal exponentiell zu erreichen bzw. erneut zu versuchen.
Wenn noch zwei Tage lang ein Fehler auftritt, wird der entsprechende Webhook deaktiviert, und der Besitzer muss ihn mit der Put /webhook-API aktualisieren, bevor er wieder funktioniert. Für z.B.
PUT {endpoint-url}/v1/webhook/{subscriptionId}
Anforderungstext:
{
"Active": "true"
}
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für