API de Notificações

Lista as notificações da organização que cobrem o projeto, de todos os canais, mais antigas primeiro (no máximo 50). status, failing_since, last_success_at e last_failure_at são deste projeto. O segredo de assinatura de um webhook nunca é retornado aqui.

Exige a capacidade de projeto; uma credencial somente de relatórios é recusada com 403 forbidden, porque a resposta inclui URLs de receptores e destinatários.

Cria uma notificação. channel email envia para recipients (owner, ou user_ids dos membros do projeto); channel webhook faz POST, assinado, para url, que segue as regras de URL de webhook (https em um host da Internet pública, porta 443 ou 8443, senão webhook_url_rejected). conditions lista as mudanças de estado da tela em que ela dispara; uma notificação por e-mail precisa de pelo menos uma, um webhook precisa de conditions ou event_types. screen_tags limita conditions a telas com qualquer uma dessas tags; vazio significa todas as telas, ou audience diz quais telas nas regras de um público-alvo de campanha. min_severity e severity filtram e classificam os avisos, e active_hours retém ou descarta os avisos fora de suas janelas.

Uma condição só notifica depois de durar hold_minutes (padrão 10), e um aviso de resolução é enviado quando ela se normaliza depois de um aviso enviado. A notificação cobre somente este projeto; uma organização tem no máximo 50 notificações, sem contar as padrão que o sistema cria (notification_limit_reached).

O segredo de assinatura de um webhook é gerado pelo servidor e retornado apenas nesta resposta e em rotate-secret; guarde-o. Repetir a requisição exatamente igual, com o mesmo Idempotency-Key, retorna esta mesma resposta, com o segredo, por vinte e quatro horas. Os avisos começam com o primeiro evento depois de notification.created.

Exige a capacidade de projeto; uma credencial somente de relatórios é recusada com 403 forbidden, porque a resposta inclui a URL do receptor ou os destinatários.

Altera qualquer um entre description (vazio a limpa), conditions, screen_tags, audience, min_severity, severity, active_hours (null limpa cada um destes), hold_minutes, recipients (email), url e event_types (webhook), destination e telegram_chat_id (Slack, Teams, PagerDuty e Telegram), enabled e snoozed_until; channel nunca muda.

Um campo do outro canal é invalid_request. Uma nova url é verificada como na criação.

Definir enabled como true em uma notificação desativada limpa seu estado de falha e começa no evento que registra a mudança; nada do período em que ela esteve desativada é enviado, e os avisos ainda pendentes de antes da desativação são marcados como falhos com webhook_disabled. snoozed_until não envia nada até aquele instante (no máximo 30 dias à frente; null encerra o silenciamento); os avisos que vencem nesse intervalo são ignorados (snoozed).

Registra notification.updated. If-Match protege a revisão. Aqui só muda uma notificação que cobre somente este projeto; uma que cobre também outros projetos da organização é notification_covers_other_projects e muda pela página Notificações da organização.

Exclui a notificação e registra notification.deleted. Seus avisos pendentes são marcados como falhos com webhook_deleted; seu registro de entregas deixa de estar acessível e expira com a retenção de eventos. Aqui só é excluída uma notificação que cobre somente este projeto (notification_covers_other_projects caso contrário).

Somente notificações de webhook (qualquer outro canal retorna invalid_request). Substitui o segredo de assinatura e retorna a notificação com o novo em secret; o segredo antigo deixa de assinar imediatamente, e no máximo uma tentativa já em andamento ainda pode chegar assinada com o antigo, então aceite os dois por um curto período. Registra notification.updated com details.changed [secret].

Uma nova tentativa exata com a mesma Idempotency-Key retorna o mesmo novo segredo por vinte e quatro horas.

Registra um evento de projeto notification.test e enfileira uma entrega dele somente para esta notificação (nenhuma outra notificação recebe notification.test).

Um webhook recebe o evento como corpo da requisição; uma notificação por e-mail envia um e-mail de teste aos destinatários; uma notificação do Slack, Teams ou Telegram publica uma mensagem de teste; uma notificação do PagerDuty aciona um evento informativo e o resolve na hora.

Funciona em uma notificação desativada ou silenciada, é tentado uma única vez (sem novas tentativas) e nunca altera o estado de falha da notificação. Consulte o registro de entregas para ver o resultado.

O registro de entregas da notificação, evento mais recente primeiro. Uma linha por evento e, para um aviso de tela, por condição desse evento; as novas tentativas atualizam a linha e GET .../deliveries/{delivery_id}/attempts lista as tentativas mais recentes dela. Um aviso que nunca precisou ser enviado é ignorado, com o motivo.

As linhas são retidas como os eventos (a retenção de eventos do plano, no mínimo a janela de 24 horas de novas tentativas). Devolva next_cursor como antes para obter a próxima página.

As tentativas de uma entrega, mais recentes primeiro, apenas as 20 últimas, mantidas junto com a linha da entrega e pelo mesmo tempo que ela. Cada uma tem seu número de tentativa, quando terminou, o status HTTP do receptor (null quando ninguém respondeu ou para e-mail), a classe de erro (null em caso de sucesso) e a duração.

Uma entrega que não pertence a esta notificação, ou uma notificação de outro projeto, retorna not_found.

Volta a enviar os e-mails de uma notificação a uma pessoa que os interrompeu com o link de cancelamento do e-mail (Notification.unsubscribed lista quem fez isso). Idempotente: uma pessoa que não está interrompida não altera nada, e a resposta é a notificação como está.

Uma mudança aumenta a revisão e adiciona notification.updated com os detalhes change resubscribed, user_id e via api. Uma sessão do painel pode reinscrever qualquer pessoa do projeto; uma credencial de agente precisa da capacidade de escrita do projeto. O caminho de volta da própria pessoa é o botão Resubscribe na página com a qual o link de cancelamento responde.

O link no rodapé de um e-mail de alerta. Ele não carrega sessão nem bearer; o token t, criado pelo screenRIG para uma notificação n e uma pessoa u, é toda a autoridade, nunca expira e é válido enquanto a versão da chave de emissão que ele nomeia for mantida.

A resposta é uma página que pergunta se os e-mails dessa notificação devem ser interrompidos para essa pessoa e que não altera nada, de modo que um verificador de e-mail que abre o link não interrompe nada; o botão dela envia para este caminho. Uma pessoa já interrompida vê uma página cujo botão a reinscreve.

Qualquer token, notificação ou pessoa que não corresponda, e uma notificação que foi excluída ou que não é por e-mail, recebe a mesma página 404. A página não tem scripts e envia apenas para esta origem. No máximo 30 requisições por minuto por endereço (rate_limited).

Interrompe os e-mails de uma notificação para a pessoa a quem o link se destina. A consulta é a do link GET; o corpo não é lido, de modo que tanto a requisição de um clique RFC 8058 de um provedor de e-mail (List-Unsubscribe=One-Click, dos cabeçalhos List-Unsubscribe e List-Unsubscribe-Post que cada e-mail de alerta e de teste traz) quanto o botão da página funcionam.

Só essa pessoa é interrompida, e só para essa notificação; os outros continuam recebendo e-mails, e a pessoa continua entre os destinatários (recipients). É idempotente. Na primeira vez, aumenta a revisão e adiciona notification.updated com os detalhes change unsubscribed, user_id e via email_link.

A página com que responde tem um botão Resubscribe (POST /api/notifications/resubscribe); um membro do projeto vê as pessoas interrompidas em Notification.unsubscribed. Quando ninguém sobra para receber e-mail, um aviso é ignorado como no_recipients. Qualquer link que não corresponda recebe a página 404 do GET. No máximo 30 requisições por minuto por endereço (rate_limited).

Desfaz POST /api/notifications/unsubscribe para a pessoa a quem o link se destina: o botão Resubscribe da página com que responde. O mesmo link, a mesma autoridade e a mesma página 404; idempotente. Uma mudança aumenta a revisão e adiciona notification.updated com os detalhes change resubscribed, user_id e via email_link. No máximo 30 requisições por minuto por endereço (rate_limited).