API de Gatilhos de alerta

Lista os gatilhos do projeto (CAP e de sobreposição), do mais antigo ao mais recente (no máximo 20), cada um com sua url de entrada, seu username e o último alerta ou estado de sobreposição. Nenhum segredo é devolvido aqui.

Cria um gatilho de alerta CAP: uma URL de entrada para a qual um sistema de notificação de emergência (Everbridge, Rave, Alertus, relés IPAWS e outros emissores CAP 1.2) envia alertas, com credenciais HTTP Basic.

A resposta é o único lugar onde a senha aparece (com a resposta de rotação): armazene-a no sistema de envio imediatamente. target é uma tag (toda tela ativa com ela quando o alerta chega) ou até 500 screen_ids.

Um alerta assume todas as telas-alvo com uma playlist padrão até o <expires> do alerta, ou para default_for_seconds (60 a 604800, padrão 3600); veja POST /api/triggers/{id}/cap. Uma organização tem no máximo 20 gatilhos em todos os seus projetos (trigger_limit_reached). Acrescenta trigger.created.

Uma nova tentativa exata com a mesma Idempotency-Key retorna esta mesma resposta, senha incluída, por vinte e quatro horas.

O pull opcional acrescenta fontes CAP que a plataforma lê para o gatilho (veja CapPull); a url de entrada continua funcionando ao lado. kind overlay cria, em vez disso, o segundo tipo: uma url de entrada (POST /api/triggers/{id}/overlay) em que qualquer sistema (Home Assistant, uma câmera, uma ferramenta de alertas) publica poucas palavras, exibidas nas telas de destino como uma faixa sobre o que está sendo exibido (overlay.show bar, na borda inferior ou superior) ou como uma tomada de controle (overlay.show takeover) enquanto um alerta durar; veja TriggerOverlay.

Com signing true, a resposta também traz o segredo de assinatura uma única vez. verify faz a assinatura própria de um fornecedor (GitHub, Stripe, Shopify, Slack, Linear, Vercel, Asana ou qualquer remetente HMAC) autenticar uma postagem no lugar da senha, que continua funcionando ao lado; ele não pode ser combinado com signing, e o segredo dele é selado e nunca devolvido, só uma dica dele. handshake nomeia um handshake de fornecedor que a URL responde (Microsoft Graph, monday.com, Trello ou Azure Event Grid; verify slack e asana respondem ao deles).

A duração de exibição do overlay vai de 10 a 604800 segundos (padrão 600). Um gatilho cujo seletor alcança uma tela protegida é protected_target (409), e uma falha na leitura da proteção da tela é dependency_unavailable (500, repita a mesma requisição); um gatilho não está disponível para um chamador limitado a telas.

Um gatilho com seu último alerta ou, em um gatilho de sobreposição, seus alertas ativos (o mais recente primeiro, o primeiro é exibido), as contagens de distribuição e se há trabalho pendente. Um alerta além do seu until é lido como encerrado com ended_reason expired.

Altera um gatilho sem mudar sua URL nem seu segredo: label, target, default_for_seconds, o pull de um gatilho CAP (null o remove) e, em um gatilho de sobreposição, overlay.edge, style (substitui todo o estilo; null o limpa), mapping (null o remove), enabled, signing, verify (null o remove; sem segredo, mantém o armazenado quando o fornecedor é o mesmo) e handshake (null o remove).

Um gatilho de sobreposição desativado responde ao remetente com o mesmo 404 de um segredo errado. Ativar a assinatura devolve o segredo de assinatura uma só vez nesta resposta. Uma faixa se reposiciona nas novas telas de destino e na nova borda; o novo destino de um gatilho de tomada de controle vale a partir do próximo alerta que começar. Acrescenta trigger.updated com details.changed. If-Match protege a revisão.

Toda atualização é verificada no alvo que o gatilho terá, o novo ou, senão, o armazenado: um alvo que alcança uma tela protegida é protected_target (409), qualquer que seja o membro que altera, e uma falha na leitura da proteção da tela é dependency_unavailable (500, repita a mesma requisição).

Exclui o gatilho. Sua URL deixa de funcionar na hora, e sua playlist de alerta e as imagens estáticas (ou as faixas, a playlist e o cartão de um gatilho de sobreposição) são excluídas. Um gatilho que exibe um alerta, ou ainda está encerrando um, é recusado com resource_conflict; encerre-o primeiro. Acrescenta trigger.deleted. If-Match protege a revisão.

Substitui a senha do gatilho e devolve a nova, uma só vez. A senha antiga deixa de funcionar na hora; atualize o sistema remetente. Com signing true no corpo, substitui em vez disso o segredo de assinatura de um gatilho de sobreposição e devolve esse, uma só vez (400 invalid_request quando o gatilho não assina). Acrescenta trigger.updated com details.rotated.

If-Match protege a revisão.

Exibe um alerta de Exercício de um minuto (um cartão azul com uma faixa amarela EXERCISE) nas telas do gatilho, exatamente como um alerta recebido, para que o direcionamento e as telas possam ser verificados sem o sistema de envio. Recurso resource_conflict recusado enquanto o gatilho exibe um alerta, para que um teste nunca substitua um real.

Uma nova tentativa exata com a mesma Idempotency-Key responde com outcome duplicate. Um gatilho de sobreposição exibe o alerta screenrig-test (label Test, title Test overlay) por um minuto e responde com um TriggerOverlayReceipt.

Encerra o alerta do gatilho (ended_reason cleared) e limpa as tomadas que ele definiu. Uma tela que outra tomada substituiu desde então permanece inalterada. Um gatilho sem alerta ativo responde inalterado. Adiciona trigger.alert_received com resultado ended.

Em um gatilho de sobreposição, o corpo pode nomear um alerta (alert_id); sem ele todos os alertas terminam, e o fim do último abaixa a faixa ou encerra as tomadas de controle.

A URL para a qual um sistema de notificação de emergência envia um alerta CAP 1.2 (qualquer tipo de conteúdo XML, no máximo 256 KiB). Autentica com as credenciais HTTP Basic do gatilho: o nome de usuário é o id do gatilho, a senha é a retornada por create ou rotate.

Uma mensagem com status Atual ou Exercício e Alerta msgType exibe um cartão em tela cheia (título, evento, descrição, instrução e remetente, vermelho para Extremo, Grave ou sem severidade, âmbar para Moderado, azul para Menor; Exercício adiciona um banner amarelo EXERCÍCIO) em todas as telas-alvo com uma playlist padrão, até <expires>, ou para default_for_seconds, no máximo 7 dias.

Uma Atualização que referencia o alerta mostrado o redesenha no lugar e move os takeovers quando <expires> mudou. Um Cancelamento que o referencia, ou qualquer mensagem com responseType AllClear, o encerra e limpa os takeovers que definiu. Um gatilho mostra um alerta: um novo Alerta substitui o mostrado.

Mensagens de teste, sistema e rascunho, Ack e Erro, um alerta já expirado e um Cancelamento de alerta não exibido são ignorados; o mesmo remetente e identificador duas vezes é duplicado. A resposta é um recibo nomeando o resultado; as telas são escritas logo após (alert.screens.pending).

Os takeovers ignoram os limites de taxa de controle da tela e nunca são medidos ou recusados por saldo. Acrescenta trigger.alert_received.

A URL em que um sistema externo (Home Assistant, uma câmera, um sensor de porta, uma ferramenta de alertas ou um fornecedor que assina os próprios webhooks) publica para que as telas do gatilho exibam poucas palavras. Ele se autentica com o segredo próprio do gatilho no cabeçalho Authorization: Bearer <secret>, ou com HTTP Basic usando o id do gatilho como usuário.

Quando o gatilho foi criado com verify, uma assinatura válida no cabeçalho próprio desse fornecedor (veja WebhookVerifyWrite) autentica a postagem no lugar do segredo, que continua funcionando ao lado.

Quando o gatilho assina, também é exigido ScreenRig-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" under the signing secret>, e t deve estar a no máximo cinco minutos do relógio do servidor.

Um gatilho desconhecido, um gatilho CAP, um segredo ou uma assinatura errados ou ausentes, um carimbo de data e hora vencido, um gatilho desativado e todo GET recebem o mesmo 404 not_found; o projeto vê o motivo no registro de entregas do gatilho.

Um gatilho configurado para um handshake de fornecedor o responde primeiro, antes de qualquer credencial ser pedida, a uma solicitação que é esse handshake: o desafio url_verification do Slack (assinado), o validationToken do Microsoft Graph, o X-Hook-Secret do Asana (guardado selado como o segredo de assinatura dos eventos dele), o challenge do monday.com, o SubscriptionValidationEvent do Azure Event Grid e a verificação HEAD do Trello (a operação head desta URL).

Um handshake não altera nenhum alerta, nunca é cobrado e não gasta orçamento de taxa, e é registrado no registro de entregas com o resultado handshake.

O corpo, de no máximo 256 KiB, é JSON, application/x-www-form-urlencoded ou multipart/form-data (cada campo de texto é body.<field>, as partes de arquivo são ignoradas e contadas no registro de entregas); com um mapping, o modelo monta a requisição a partir de body e query. alert_id nomeia o alerta: uma postagem com um id ativo atualiza esse alerta em vez de empilhar outro, e o alerta iniciado mais recentemente é exibido.

Cada disparo ou atualização mantém seu alerta por duration a partir daquele envio (de 10 a 604800 segundos, ou 10s, 5m, 2h, 1d, ou until_cleared; por padrão o do gatilho), de modo que um sensor que continua enviando mantém a sobreposição.

Um envio com clear true, ou um state que significa que acabou (off, closed, clear, cleared, resolved, ok, normal, inactive, ended), encerra o alerta com esse id, ou todos os alertas se não houver id. Um disparo ou atualização é uma solicitação de API cobrada; um encerramento é gratuito e nunca é recusado por saldo.

Idempotency-Key (de 8 a 200 caracteres) responde à nova tentativa de um remetente com o primeiro recibo por vinte e quatro horas. No máximo 120 envios por minuto por gatilho.

A verificação que o Trello faz de um novo webhook. Ela responde 200 sem corpo para um gatilho cujo handshake é trello, e o único 404 not_found para qualquer outro gatilho, endereço e solicitação, então um visualizador de links não descobre nada. Ela não grava nada, nunca é cobrada e não gasta orçamento de taxa; a verificação respondida fica no registro de entregas com o resultado handshake.

Todo GET responde o 404 e não lê nada.

As postagens para um gatilho de sobreposição nos últimos sete dias, das mais recentes para as mais antigas (no máximo 100), com quando cada uma chegou, como cada uma terminou (shown, updated, unchanged, ended, ignored, refused, invalid ou handshake), por que uma recusada ou inválida foi assim (credentials, signature, signature_missing, signature_invalid, timestamp_missing, timestamp_stale, secret_pending, handshake_invalid, disabled, body, mapping, field, rate_limited, payment_required, internal), o status, o tamanho, o número de partes de arquivo que uma postagem multipart trazia (ignoradas) e o ID da solicitação.

Não guarda corpo, cabeçalho nem credencial. Um gatilho CAP não tem nenhuma.