Webhooks - Como funcionam e como utilizá-los?
Introdução
Um webhook é um endpoint HTTP que os integradores devem implementar para receber notificações em tempo real de eventos que ocorrem no Situator.
Os webhooks podem ser utilizados para:
Monitorar os eventos de acesso. Por exemplo:
Para monitorar a entrada e saída de moradores em tempo real;
Para monitorar a entrada de visitantes e notificar as pessoas responsáveis;
Monitorar as ocorrências. Por exemplo:
Ocorrências de interfone;
Ocorrências de pânico;
Ocorrências de porta arrombada;
Ocorrências de porta deixada aberta;
Monitorar o cadastro de pessoas. Por exemplo:
Para notificar outros sistemas de que houve o cadastro, edição ou exclusão de uma pessoa;
Funcionamento
Quando um evento acontece no Situator, o Situator coloca o evento em um buffer para ser enviado para os webhooks cadastrados.
Quando um evento é colocado no buffer de eventos, o Situator imediatamente retira eles do buffer e envia eles para o integrador.
Caso o integrador esteja offline ou ocupado demais para processar os eventos, os eventos serão descartados.
Enquanto o Situator estiver enviando os eventos para o integrador, os novos eventos que forem ocorrendo serão armazenados no buffer. Caso o integrador demore muito tempo para processar a requisição, isso pode encher o buffer com eventos que estão esperando para serem processados. Se o buffer chegar em 100 eventos, os novos eventos serão descartados pelo Situator.
Considerações
Tendo em vista que:
O Situator não armazena os eventos a serem enviados para o integrador;
O Situator não possui nenhum mecanismo de retransmissão em caso de falha;
O Situator pode descartar os eventos se o integrador estiver sobrecarregado;
Para integrações mais complexas, nós recomendamos que o integrador utilize uma ferramenta para processamento de mensagens. Como por exemplo: RabbitMQ e o AmazonMQ. Neste caso, nós não nos responsabilizamos pelas mensagens perdidas ou descartadas na transmissão.
Detalhamento
Para receber os eventos do Situator, é preciso:
1. Criar endpoint
A url deste endpoint pode ser especificada pelo integrador, mas o método precisa ser POST. Fica a critério do integrador definir a URL na qual ele espera receber os eventos do Situator. Por convenção, nós sugerimos /api/situator/events.
Além disso, a autenticação neste endpoint deve ser feita por um token de identificação. Este token de autenticação deve ser uma string aleatória criada pelo integrador no cadastro do webhook.
2. Cadastrar um webhook
Um nome identificador do webhook;
Um status para ativar ou desativar o webhook;
Um token de autenticação criado pelo integrador;
Uma descrição;
A URL do endpoint criado pelo integrador;
Por exemplo:
1
2
3
4
5
6
7
{
"active": true,
"name": "Integrador XYZ",
"token": "6R7zvBFrjAheqw5L",
"description": "Exemplo de integração webhook",
"url": "https://integrador.com.br/api/situator/events%22
}3. Cadastrar portas
Caso o integrador não queira monitorar esses eventos de acesso, basta avançar para a próxima etapa.
Para monitorar os eventos de acesso de uma porta, o integrador deve primeiro buscar a lista de portas disponíveis pelo endpoint GET /api/webhooks/{webhookId}/doors. Caso essa lista não retorne nenhuma porta, é provável que o servidor não está corretamente configurado e licenciado.
Uma vez que o integrador buscou a lista de portas e selecionou aquelas que ele tem interesse em monitorar, ele pode cadastrar a lista completa de portas pelo endpoint PUT /api/webhooks/{webhookId}/doors. Por exemplo:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"doors": [
{
"serverId": 1001,
"doorId": 1
},
{
"serverId": 1002,
"doorId": 1
},
{
"serverId": 1003,
"doorId": 1
},
{
"serverId": 1003,
"doorId": 2
}
]
}O Situator pode ter muitas portas cadastradas, mas nem todas elas precisam ser monitoradas. Se o integrador monitorar todas as portas, é melhor estar muito bem preparado para receber uma quantidade grande de eventos.
4. Cadastrar ocorrências
Em seguida, o integrador deve definir quais ocorrências ele deseja monitorar.
Caso o integrador não queira monitorar as ocorrências, basta avançar para a próxima etapa.
Para monitorar as ocorrências, o integrador deve primeiro buscar a lista de eventos disponíveis pelo endpoint GET /api/webhooks/{webhookId}/events. Em seguida, o integrador deve selecionar os eventos que precisam ser monitorados.
Uma vez que o integrador buscou a lista de portas e selecionou aquelas que ele tem interesse em monitorar, ele pode cadastrar a lista completa de portas pelo endpoint PUT /api/webhooks/{webhookId}/events. Por exemplo:
1
2
3
4
5
6
7
8
9
10
{
"events": [
{
"eventId": 11
},
{
"eventId": 12
}
]
}5. Receber eventos
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
"name": "Teste",
"token": "1234",
"events": [
{
"type": "access",
"dateTime": "2019-02-15T17:21:48.1201-02:00",
"id": 1891,
"accountId": 1000,
"zoneId": 1001,
"serverId": 1000,
"doorId": 1,
"personId": 1,
"direction": 1,
"authorized": true,
"openingType": 7
},
{
"type": "person",
"dateTime": "2019-02-15T17:22:52.23459-02:00",
"subtype": 1,
"accountId": 1000,
"personId": 31
}
{
"type": "access",
"dateTime": "2019-02-15T17:23:52.778011-02:00",
"id": 1892,
"accountId": 1000,
"zoneId": 1001,
"serverId": 1000,
"doorId": 2,
"personId": 2,
"direction": 2,
"authorized": true,
"openingType": 7
}
]
}O objeto reportado pelo Situator contém o nome do webhook, o token de identificação e um array de eventos. Mais informações sobre esse objeto podem ser encontradas na aba Response do endpoint GET /api/webhooks/help.
O nome do webhook serve apenas para identificação da origem do evento. Ele é útil para rastrear e investigar problemas.
O token de identificação deve ser utilizado pelo integrador para validar se ele corresponde com o mesmo token que foi cadastrado no webhook. Se o token for diferente do esperado, o integrador deve registrar um log e descartar o evento.
A lista de eventos é um array de objetos que estendem de WebhookNotificationVO. Ou seja, todos os eventos possuem os campos type e dateTime.
1
2
3
4
WebhookNotificationVO {
type (string, read only): All events have a type,
dateTime (string): All events have date time
}O campo type deve ser utilizado na hora de desserializar o json em um objeto de acordo com o seu tipo.
Caso o campo type seja access, isso significa que o objeto é um evento de acesso. Neste caso, os campos deste objeto são:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
WebhookAccessEventVO {
type (string, read only): Constant value: "access" ,
dateTime (string): Date time of the access transaction ,
id (integer): Access transaction id ,
accountId (integer): Account id ,
zoneId (integer): Access zone id ,
serverId (integer, optional): Server id ,
doorId (integer, optional): Door id ,
personId (integer, optional): Person id. If null, unknown ,
vehicleId (integer, optional): If set, the access was made with a vehicle ,
direction (integer): Access direction Values: 0 = None;1 = Entry;2 = Exit ,
authorized (boolean): If false, the access was denied. ,
duress (boolean, optional): If true, it is an access made under duress. ,
openingType (integer): Opening type. Values: 0 = None;1 = Fingerprint;2 = Card;3 = Password;4 = Control;5 = QrCode;6 = VirtualKey;7 = RemoteOpening;8 = ButtonHole;9 = Facial;10 = FingerprintAndCard;11 = CardAndPassword;12 = CardAndFingerprintAndPassword;13 = FingerprintAndPassword,
visitorId (integer, optional): Visitor id.
}Caso o campo type seja occurrence, isso significa que o objeto é uma ocorrência. Neste caso, os campos deste objeto são:
1
2
3
4
5
6
7
8
9
10
11
WebhookOccurrenceEventVO {
type (string, read only): Constant value: "occurrence" ,
dateTime (string): Date time of the occurrence ,
subtype (integer): Event subtype Values: 0 = None;1 = Created;2 = Incremented;3 = Changed ,
id (integer): Occurrence id ,
accountId (integer): Account id ,
eventId (integer): Event id ,
zoneId (integer): Zone id ,
personId (integer, optional): Person id ,
visitorId (integer, optional): Viositor id
}Caso o campo type seja person, isso significa que o objeto é um evento de cadastro de pessoa. Neste caso, os campos deste objeto são:
1
2
3
4
5
6
7
WebhookPersonEventVO {
type (string, read only): Constant value: "person" ,
dateTime (string): Date time of the event ,
subtype (integer): Event subtype Values: 0 = None;1 = Created;3 = Changed;4 = Deleted ,
accountId (integer): Account id ,
personId (integer): Person id
}Related Articles
Como criar um horário de acesso GLOBAL no Situator?
O Horário de Acesso funciona como um limitador de horário para Zonas, por exemplo, se temos um horário de acesso "Comercial" que esta configurado os dias de Segunda a Sexta das 09:00 as 18:00 e associarmos este horário a uma pessoa ou zona, a pessoa ...O que é um perfil de usuário no Situator?
Perfis de usuários são os tipos dos usuários que você pode criar dentro do Situator, você pode utilizar tanto os perfis pré-definidos quando personalizar um perfil próprio para utilização. - Primeiramente vá até o Menu > Configurações > Usuários > ...Como adicionar um Utech no Situator?
ATENÇÃO NÃO UTILIZE EQUIPAMENTOS COM A FIRMWARE DIFERENTE DA HOMOLOGADA. Consulte os dispositivos suportados clicando aqui. Este dispositivo precisa saber para onde mandar os eventos e precisamos pré-definir um usuário/senha/porta para autenticação ...Como enviar um e-mail no Situator?
Antes de prosseguir com o tutorial você precisa que o seu servidor de e-mail já esteja configurado. * Para configurar o seu servidor de e-mail, clique aqui. - Primeiramente vá até a tela de Monitoramento > Selecione uma Conta; - Vá até a aba ...Como habilitar https no Situator?
Podemos implementar no Situator 2 tipos de certificados, os válidos e os inválidos, neste material vamos aprender a adequar o Situator a ambos. Antes de mais nada precisamos que o Situator esteja com a versão 5.23.1.1 ou superior e com a porta HTTPS ...