API para registrar & administrar webhooks
/webhook
Punto final de API para administrar suscripciones a eventos dentro de Kaizala.
WebHooks es un patrón HTTP ligero que proporciona un modelo de publicador o suscriptor simple para conectar las API web y los servicios SaaS. Cuando se produce un evento en Kaizala, se envía una notificación en forma de solicitud HTTP POST a los suscriptores registrados. La solicitud POST contiene información sobre el evento que permite al receptor actuar en consecuencia.
Con WebHooks, puede suscribirse a varios eventos que se producen dentro de un contexto de grupo de conversación en Kaizala.
POST /webhook
POST {endpoint-url}/v1/webhook
Para asegurarse de que el punto de conexión del servicio webhook es auténtico y funciona, comprobaremos la dirección URL de devolución de llamada antes de crear la suscripción. Para la comprobación, le enviaremos un token de validación que debe enviarnos de vuelta en 5 segundos. Leer más
Parámetros de solicitud
| Parámetro | Tipo | ¿Opcional? | Description | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Encabezado HTTP | accessToken | Cadena | No | Token de acceso recibido desde el punto de conexión de autenticación | Encabezado HTTP | Content-Type | Cadena | No | "application/json" |
Cuerpo de la solicitud
| Parámetro | Tipo | ¿Opcional? | Description |
|---|---|---|---|
| objectId | Cadena | No | Identificador que representa el objeto en el que se deben crear los webhooks. Para ObjectType=Group, el identificador de su grupo, Para ObjectType=Action, su actionId, For ObjectType=ActionPackage, su action-package-id |
| objectType | Cadena | No | Enumeración: "Group"/"Action"/"ActionPackage" |
| eventTypes | Matriz | No | Matriz de diferentes tipos de eventos a los que debe suscribir el webhook. Los eventos admitidos son: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | Cadena | No | Dirección URL HTTPS a la que deben notificarse los eventos suscritos |
| callBackToken | Cadena | Sí | Parámetro opcional que puede establecer que se enviará en el encabezado HTTP "kz-callback-token" con cada devolución de llamada realizada por el WebHook. |
| callBackContext | Cadena | Sí | Parámetro opcional que puede establecer que se enviará en la carga json como "contexto" con cada devolución de llamada realizada por El WebHook |
| Validez | Cadena | Sí | Validez para que el WebHook esté activo en formato EPOCH. El valor predeterminado es de 2 años |
Cuerpo de la respuesta
| Parámetro | Tipo | Description |
|---|---|---|
| webhookId | Cadena | Identificador que representa el webHook creado |
Cuerpo de la solicitud: suscribirse a todos los eventos a nivel de grupo
{
"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"
}
Puede encontrar el esquema de respuesta de webhook para eventos registrados en Kaizala aquí.
Nota: Kaizala garantiza al menos una entrega una vez de la respuesta del webhook. Puede ocurrir, en ciertos casos, que Kaizala pueda enviar una respuesta de webhook duplicada para el mismo evento.
Obtener /webhook
GET {endpoint-url}/v1/webhook
Parámetros de solicitud
| Parámetro | Tipo | ¿Opcional? | Description | |
|---|---|---|---|---|
| Encabezado HTTP | accessToken | Cadena | No | Token de acceso recibido desde el punto de conexión de autenticación |
| Parámetro de consulta | objectId | Cadena | No | Identificador que representa el objeto en el que se deben crear los webhooks. Para ObjectType=Group, el identificador de su grupo, Para ObjectType=Action, su actionId, For ObjectType=ActionPackage, su action-package-id |
| Parámetro de consulta | objectType | Cadena | No | Enumeración: "Group"/"Action"/"ActionPackage" |
Cuerpo de la respuesta
| Parámetro | Tipo | Description |
|---|---|---|
| webhooks | Matriz de objetos JSON | Matriz de webhooks suscritos en el objectId |
Estructura JSON para cada webhook individual en los webhooks de matriz[]:
| Parámetro | Tipo | Descripción |
|---|---|---|
| id | Cadena | Identificador de webhook |
| objectId | Cadena | Identificador de objeto |
| objectType | Cadena | Enumeración: "Group"/"Action"/"ActionPackage" |
| eventos | Cadena[] | Lista de eventos con cada valor como "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | Cadena | Dirección URL de devolución de llamada a la que deben notificarse los eventos suscritos |
| callBackToken | Cadena | Parámetro que se enviará en el encabezado HTTP "kz-callback-token" con cada devolución de llamada realizada por el WebHook. |
| callBackContext | Cadena | Parámetro enviado en la carga JSON como "context" con cada devolución de llamada realizada por WebHook |
| Validez | Cadena | Validez para que el WebHook esté activo en formato EPOCH. |
| Activo | Booleano | True, si el estado del webhook está activo |
Respuesta JSON de ejemplo
{
"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
}
]
}
Eliminar /webhook
DELETE {endpoint-url}/v1/webhook
Parámetros de solicitud
| Parámetro | Tipo | ¿Opcional? | Description | |
|---|---|---|---|---|
| Encabezado HTTP | accessToken | Cadena | No | Token de acceso recibido desde el punto de conexión de autenticación |
| Parámetro Path | webhookId | Cadena | No | Identificador de webhook |
PUT /webhook
PUT {endpoint-url}/v1/webhook/{webhookId}
Se puede actualizar cualquier parámetro para el webhook. El cuerpo de la solicitud puede contener 1 o más parámetros, según sea necesario.
Parámetros de solicitud
| Parámetro | Tipo | ¿Opcional? | Description | |
|---|---|---|---|---|
| Encabezado HTTP | accessToken | Cadena | No | Token de acceso recibido desde el punto de conexión de autenticación |
| Parámetro Path | webhookId | Cadena | No | Identificador de webhook |
Cuerpo de la solicitud
| Parámetro | Tipo | ¿Opcional? | Description |
|---|---|---|---|
| objectId | Cadena | Sí | Identificador que representa el objeto en el que se deben crear los webhooks. Para ObjectType=Group, el identificador de su grupo, Para ObjectType=Action, su actionId, For ObjectType=ActionPackage, su action-package-id |
| objectType | Cadena | Sí | Enumeración: "Group"/"Action"/"ActionPackage" |
| eventTypes | Matriz | Sí | Matriz de diferentes tipos de eventos a los que debe suscribir el webhook. Los eventos admitidos son: "ActionCreated","ActionResponse","SurveyCreated","JobCreated","SurveyResponse","JobResponse","TextMessageCreated","AttachmentCreated","Announcement","MemberAdded","MemberRemoved","GroupAdded","GroupRemoved" |
| callBackUrl | Cadena | Sí | Dirección URL HTTPS a la que deben notificarse los eventos suscritos |
| callBackToken | Cadena | Sí | Parámetro opcional que puede establecer que se enviará en el encabezado HTTP "kz-callback-token" con cada devolución de llamada realizada por el WebHook. |
| callBackContext | Cadena | Sí | Parámetro opcional que puede establecer que se enviará en la carga json como "contexto" con cada devolución de llamada realizada por El WebHook |
| Validez | Cadena | Sí | Validez para que el WebHook esté activo en formato EPOCH. El valor predeterminado es de 2 años |
| Activo | Booleano | Sí | Cambie el estado del webhook a Activo, si el valor es true. |
Ejemplo de cuerpo de solicitud
{
"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"
}
Deshabilitación automática de webhooks
Para mejorar la confiabilidad de nuestros webhooks, recientemente hemos agregado la lógica reintentar y deshabilitar. La dirección URL/punto de conexión de devolución de llamada registrada con un webhook, si no es accesible o no responde con un código de estado distinto de 2xx (>=3xx), nuestro servicio intentará alcanzarlo o reintentarlo 6 veces de forma exponencial en un intervalo de 2 días.
Si sigue produciendo errores durante 2 días, el webhook correspondiente se deshabilitará y el propietario debe actualizarlo con la API Put /webhook antes de que empiece a funcionar de nuevo. Por ejemplo,
PUT {endpoint-url}/v1/webhook/{subscriptionId}
Cuerpo de la solicitud:
{
"Active": "true"
}
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de