APIs para registrar & gerenciar webhooks
/webhook
Ponto de extremidade da API para gerenciar assinaturas para eventos dentro do Kaizala.
O WebHooks é um padrão HTTP leve que fornece um modelo simples de editor/assinante para unir APIs Web e serviços SaaS. Quando um evento acontece em Kaizala, uma notificação é enviada na forma de uma solicitação HTTP POST para assinantes registrados. A solicitação POST contém informações sobre o evento, o que torna possível que o receptor atue de acordo.
Usando WebHooks, você pode assinar vários eventos que ocorrem dentro de um contexto de grupo de conversa em Kaizala.
POST /webhook
POST {endpoint-url}/v1/webhook
Para garantir que o ponto de extremidade do serviço webhook seja autêntico e funcionando, verificaremos sua URL de retorno de chamada antes de criar a assinatura. Para verificação, enviaremos um token de validação que você precisa para nos enviar de volta dentro de 5 segundos. Leia Mais
Parâmetros de solicitação
| Parâmetro | Tipo | Opcional? | Descrição | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
| Cabeçalho HTTP | accessToken | Cadeia de caracteres | Não | Token de Acesso recebido do ponto de extremidade de auth | Cabeçalho HTTP | Content-Type | Cadeia de Caracteres | Não | "application/json" |
Corpo da solicitação
| Parâmetro | Tipo | Opcional? | Descrição |
|---|---|---|---|
| objectId | Cadeia de caracteres | Não | Identificador que representa o objeto no qual o contexto os webhooks precisam ser criados. Para ObjectType=Group, o Identificador de seu grupo, Para ObjectType=Action, seu actionId, For ObjectType=ActionPackage, seu action-package-id |
| objectType | String | Não | Enum: "Group"/"Action"/"ActionPackage" |
| eventTypes | Matriz | Não | Matriz de diferentes tipos de eventos aos quais você precisa assinar o webhook. Os eventos com suporte são: "ActionCreated", "ActionResponse", "SurveyCreated", "JobCreated","SurveyResponse","JobResponse", "TextMessageCreated", "AttachmentCreated", "Announcement","MemberAdded","MemberRemoved", "GroupAdded", "GroupRemoved" |
| callBackUrl | Cadeia de caracteres | Não | URL HTTPS à qual os eventos inscritos precisam ser notificados |
| callBackToken | Cadeia de caracteres | Sim | Parâmetro opcional que você pode definir que será enviado no cabeçalho HTTP 'kz-callback-token' com cada chamadaBack feita pelo WebHook |
| callBackContext | Cadeia de caracteres | Sim | Parâmetro opcional que você pode definir que será enviado na carga JSON como 'context' com cada chamadaBack feita pelo WebHook |
| Validade | Cadeia de caracteres | Sim | Validade para que o WebHook esteja ativo no formato EPOCH. Padrão é 2 anos |
Corpo da resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
| webhookId | Cadeia de caracteres | Identificador que representa o WebHook criado |
Corpo da Solicitação – Assinar todos os eventos no nível 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"
}
Você pode encontrar o esquema de resposta webhook para eventos registrados em Kaizala aqui.
Nota: Kaizala garante pelo menos uma vez a entrega da resposta webhook. Pode acontecer, em certos casos, que Kaizala possa enviar resposta webhook duplicada para o mesmo evento.
Obter /webhook
GET {endpoint-url}/v1/webhook
Parâmetros de solicitação
| Parâmetro | Tipo | Opcional? | Descrição | |
|---|---|---|---|---|
| Cabeçalho HTTP | accessToken | Cadeia de caracteres | Não | Token de Acesso recebido do ponto de extremidade de auth |
| Parâmetro de consulta | objectId | Cadeia de caracteres | Não | Identificador que representa o objeto no qual o contexto os webhooks precisam ser criados. Para ObjectType=Group, o Identificador de seu grupo, Para ObjectType=Action, seu actionId, For ObjectType=ActionPackage, seu action-package-id |
| Parâmetro de consulta | objectType | String | Não | Enum: "Group"/"Action"/"ActionPackage" |
Corpo da resposta
| Parâmetro | Tipo | Descrição |
|---|---|---|
| webhooks | Matriz de Objetos JSON | Matriz de webhooks inscritos no objectId |
Estrutura JSON para cada webhook individual nos webhooks da matriz[]:
| Parâmetro | Tipo | Descrição |
|---|---|---|
| id | Cadeia de caracteres | Identificador do Webhook |
| objectId | Cadeia de caracteres | Identificador de Objeto |
| objectType | Cadeia de caracteres | Enum: "Group"/"Action"/"ActionPackage" |
| eventos | String[] | Lista de eventos com cada valor como um de "ActionCreated", "ActionResponse", "SurveyCreated", "JobCreated","SurveyResponse", "JobResponse", "TextMessageCreated", "AttachmentCreated", "Announcement", "MemberAdded","MemberRemoved", "GroupAdded", "GroupRemoved" |
| callBackUrl | Cadeia de caracteres | URL de retorno de chamada à qual os eventos inscritos precisam ser notificados |
| callBackToken | Cadeia de caracteres | Parâmetro que será enviado no cabeçalho HTTP 'kz-callback-token' com cada callBack feito pelo WebHook |
| callBackContext | Cadeia de caracteres | Parâmetro enviado na carga JSON como 'contexto' com cada retorno de chamada feito pelo WebHook |
| Validade | Cadeia de caracteres | Validade para que o WebHook esteja ativo no formato EPOCH. |
| Ativo | Booliano | True, se o estado do webhook estiver ativo |
Resposta JSON de exemplo
{
"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
}
]
}
Excluir /webhook
DELETE {endpoint-url}/v1/webhook
Parâmetros de solicitação
| Parâmetro | Tipo | Opcional? | Descrição | |
|---|---|---|---|---|
| Cabeçalho HTTP | accessToken | Cadeia de caracteres | Não | Token de Acesso recebido do ponto de extremidade de auth |
| Parâmetro Path | webhookId | Cadeia de caracteres | Não | Identificador do Webhook |
PUT /webhook
PUT {endpoint-url}/v1/webhook/{webhookId}
Qualquer parâmetro para o webhook pode ser atualizado. O Corpo da Solicitação pode conter 1 ou mais parâmetros, conforme necessário.
Parâmetros de solicitação
| Parâmetro | Tipo | Opcional? | Descrição | |
|---|---|---|---|---|
| Cabeçalho HTTP | accessToken | Cadeia de caracteres | Não | Token de Acesso recebido do ponto de extremidade de auth |
| Parâmetro Path | webhookId | Cadeia de caracteres | Não | Identificador do Webhook |
Corpo da solicitação
| Parâmetro | Tipo | Opcional? | Descrição |
|---|---|---|---|
| objectId | Cadeia de caracteres | Sim | Identificador que representa o objeto no qual o contexto os webhooks precisam ser criados. Para ObjectType=Group, o Identificador de seu grupo, Para ObjectType=Action, seu actionId, For ObjectType=ActionPackage, seu action-package-id |
| objectType | String | Sim | Enum: "Group"/"Action"/"ActionPackage" |
| eventTypes | Matriz | Sim | Matriz de diferentes tipos de eventos aos quais você precisa assinar o webhook. Os eventos com suporte são: "ActionCreated", "ActionResponse", "SurveyCreated", "JobCreated","SurveyResponse","JobResponse", "TextMessageCreated", "AttachmentCreated", "Announcement","MemberAdded","MemberRemoved", "GroupAdded", "GroupRemoved" |
| callBackUrl | Cadeia de caracteres | Sim | URL HTTPS à qual os eventos inscritos precisam ser notificados |
| callBackToken | Cadeia de caracteres | Sim | Parâmetro opcional que você pode definir que será enviado no cabeçalho HTTP 'kz-callback-token' com cada chamadaBack feita pelo WebHook |
| callBackContext | Cadeia de caracteres | Sim | Parâmetro opcional que você pode definir que será enviado na carga JSON como 'context' com cada chamadaBack feita pelo WebHook |
| Validade | Cadeia de caracteres | Sim | Validade para que o WebHook esteja ativo no formato EPOCH. Padrão é 2 anos |
| Ativo | Booliano | Sim | Altere o estado do webhook para Active, se o valor for verdadeiro |
Corpo de solicitação de amostra
{
"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"
}
Desabilitar automaticamente webhooks
Para melhorar a confiabilidade de nossos Webhooks, recentemente adicionamos a Lógica de Repetição e Desabilitação. A Url/Ponto de Extremidade de Retorno de Chamada registrada com um webhook, se não for acessível ou não responder com um código de status diferente de 2xx (>=3xx), então nosso Serviço tentará alcançá-lo/repeti-lo por seis vezes de forma exponencial em um período de 2 dias.
Se ele ainda estiver falhando por dois dias, o Webhook correspondente será desabilitado e o proprietário precisará atualizá-lo com a API Put/webhook antes de começar a funcionar novamente. Por exemplo,
PUT {endpoint-url}/v1/webhook/{subscriptionId}
Corpo da Solicitação:
{
"Active": "true"
}
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários