Skip to main content
POST
Assinar um tópico com um destino
Exige a ação IAM notifications:Subscribe. Veja NOTIFICATIONS permissões para a lista completa, o escopo de cada ação e um exemplo de política.

Autorizações

Authorization
string
header
obrigatório

Um token bearer OAuth 2.0, enviado como Authorization: Bearer <token>. Esta é a forma recomendada de autenticação.

Obtenha o token trocando o par de chaves de acesso de uma conta de serviço em POST /v1/oauth/token com grant_type=client_credentials. Esse é o fluxo padrão de credenciais de cliente; bibliotecas compatíveis com OAuth podem obter e renovar o token para você.

Os tokens duram uma hora por padrão. O mesmo par de chaves de acesso também serve como credencial AWS SigV4 para o endpoint de objetos compatível com S3, que aceita somente esse método de autenticação.

Cabeçalhos

Idempotency-Key
string

Chave opcional gerada pelo cliente que torna uma criação segura para reprodução. A reintentar uma solicitação com a mesma chave retorna o resultado original literalmente em vez de criar um recurso duplicado. A reutilização de uma chave com um corpo de solicitação diferente é rejeitada (422); uma solicitação cuja chave ainda está sendo processada retorna 409. Os registros são honrados por 24 horas. Use um UUID ou token exclusivo semelhante.

Maximum string length: 255

Parâmetros de caminho

topic_id
string<uuid>
obrigatório
Exemplo:

"a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"

Corpo

application/json
protocol
enum<string>
obrigatório
Opções disponíveis:
email,
https,
http,
queue
Exemplo:

"https"

endpoint
string
obrigatório

Endereço de email, URL http/https com esquema correspondente ao protocolo e endereço publicamente roteável ou, para queue, UUID, CRN ou nome exato de uma fila na conta e região do assinante. Filas são armazenadas e retornadas como CRNs canônicos. Assinaturas de fila já são confirmadas ao criar: o consentimento é verificado pela permissão queue:SendMessage. Email e webhooks exigem confirmação do proprietário do destino.

Maximum string length: 2048
Exemplo:

"https://hooks.example.com/basaltic"

raw_message_delivery
boolean
padrão:false

Somente http/https.

Exemplo:

false

filter_policy
object

Filtra atributos da publicação, não campos do corpo. Cada atributo deve corresponder a uma alternativa: AND entre nomes e OR dentro de cada lista. Nomes e comparações distinguem maiúsculas. Política omitida ou vazia aceita todas as mensagens.

Alternativas: strings ou números exatos, ou objetos com um operador: {"prefix": "order."}, {"suffix": ".failed"}, {"anything-but": ["debug", "trace"]}, {"exists": true}, {"exists": false} ou {"numeric": [">=", 100, "<", 1000]}. Prefixos e sufixos não podem ser vazios. anything-but aceita uma string, número ou lista de 1–50 valores.

Somente exists: false aceita atributo ausente. Exclusão também exige presença. Operadores numéricos: =, <, <=, > e >=; todos os pares devem ser verdadeiros. Valores não numéricos não correspondem. Números simples comparam representações textuais; use numeric para equivalência entre "100" e "100.0".

Até 20 nomes não vazios, com 1–50 alternativas por nome. Um operador por objeto. Não há curingas, expressões regulares, filtros no corpo ou operadores aninhados. PATCH substitui a política inteira; {} limpa e omissão preserva. Veja Políticas de filtro.

Exemplo:
delivery_policy
object

Política de tentativas. Campos omitidos herdam o tópico e depois os padrões: 6 tentativas, espera exponencial de 20s a 20min com variação aleatória e timeout de 15s. A herança ocorre por campo; alterar max_attempts preserva a curva do tópico.

redrive_policy
object

Fila da conta do assinante que recebe falhas definitivas como mensagens delivery_failure, com a notificação original e um bloco failure contendo ID, destino, tentativas, último erro e status. Sem fila, as falhas continuam disponíveis nos registros e métricas. Exige queue:SendMessage ao definir a política. Em assinaturas de fila, o destino deve ser diferente da fila assinada.

tags
object
Exemplo:

Resposta

Assinatura criada ou existente retornada.

subscription
object
obrigatório
signing_secret
string

Chave HMAC para verificar entregas por webhook. Retornada somente na primeira criação http/https; ausente para email e para assinaturas existentes.

Exemplo:

"kJ8vQ2xR5tY7uI0oP3aS6dF9gH1jK4lZ7xC0vB3nM6Q"