LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Webhooks e eventos

Usar com IA

Para onde a Luna entrega o que chega no seu número, o segredo que assina essas entregas e os tipos de evento, cada um com o esquema e um exemplo.

Eventos de webhook

Listar os endpoints de webhook

GET/v1/webhooks/endpoints

Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate). Cada endpoint traz deliveryStatus.

Autenticação
Chave de API
Escopo exigido
webhooks:read

Respostas

200Os endpoints cadastrados neste cliente, do mais recente para o mais antigo, com o limite de endpoints e se ainda dá para cadastrar outro (limit e canCreate).
  • dataarray<object>obrigatório
  • data[].idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.
  • data[].urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • data[].createdAtstringobrigatório
    Quando o endpoint foi cadastrado, em UTC.
  • data[].updatedAtstringobrigatório
    Quando ele foi alterado pela última vez, em UTC.
  • data[].previousSecretExpiresAtstring | nullobrigatório
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • data[].pausedbooleanobrigatório
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • data[].pausedAtstring | nullobrigatório
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • data[].eventTypesarray<string>obrigatório
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • data[].externalIdsarray<string>obrigatório
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • data[].phoneNumberIdsarray<string>obrigatório
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • data[].headerNamesarray<string>obrigatório
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • data[].lastDeliveryAtstring | nullobrigatório
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • data[].lastFailureAtstring | nullobrigatório
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • data[].lastHttpStatusinteger | nullobrigatório
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • data[].deliveryStatusstringobrigatório
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Valores: ok failing paused never_delivered
  • limitintegerobrigatório
    O máximo de endpoints por cliente. É o mesmo para todos, e não depende do plano.
  • canCreatebooleanobrigatório
    false quando você já chegou ao limite: POST /v1/webhooks/endpoints responderia 409. Remover um endpoint libera a vaga. A tela mostra o botão de cadastrar por este campo.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Cadastrar o endpoint de webhook

POST/v1/webhooks/endpoints

Registra a URL do seu servidor e devolve o segredo que assina as entregas. headers, opcional, leva até 5 cabeçalhos HTTP próprios que a Luna envia em cada entrega (para um gateway que exige um token fixo); os valores são segredo e nenhuma resposta os devolve.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Corpo da requisição

application/json · obrigatório

  • urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • eventTypesarray<string>opcional
    Os tipos de evento que este endpoint recebe, por exemplo ["message.received", "message.status"]. Ausente ou vazio quer dizer todos, inclusive os tipos que a Luna criar depois. Com a lista preenchida, o endpoint só recebe esses tipos, e um tipo novo não chega até você incluí-lo. O filtro é só por tipo. O evento webhook.test não é filtrável: ele só sai quando você o pede. Os tipos estão no guia Receber eventos.até 30 itens
  • externalIdsarray<string>opcional
    Os clientes seus (externalId) de que este endpoint recebe eventos, por exemplo ["cliente-42"]. Ausente ou vazio quer dizer todos. Com a lista preenchida, o endpoint só recebe eventos de números com um destes externalId, inclusive os conectados depois, e dos links de conexão com ele. Eventos que não falam de um cliente (os de template, por exemplo) só chegam se a conta do template tem um número dele. O filtro é só por identificador.até 100 itens
  • phoneNumberIdsarray<string>opcional
    Os números de que este endpoint recebe eventos: o UUID da Luna (o id de GET /v1/numbers) ou o id da Meta (metaPhoneNumberId), em qualquer mistura. A resposta devolve os ids da Meta, os mesmos que os eventos trazem em phone_number_id. Ausente ou vazio quer dizer todos. Um número que não é da conta responde 400. Para cobrir números que ainda serão conectados, use externalIds.até 100 itens
  • headersobjectopcional
    Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos.

Respostas

201O endpoint recém-criado, com o segredo de assinatura.
  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.
  • urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • createdAtstringobrigatório
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringobrigatório
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullobrigatório
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanobrigatório
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullobrigatório
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>obrigatório
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>obrigatório
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>obrigatório
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>obrigatório
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullobrigatório
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullobrigatório
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullobrigatório
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringobrigatório
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Valores: ok failing paused never_delivered
  • secretstringobrigatório
    O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Limite de endpointsJSON
{
  "error": "webhook_endpoint_limit",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Este cliente já tem o máximo de endpoints de webhook, e o limite é o mesmo para todos. Remova um endpoint com DELETE /v1/webhooks/endpoints/{id} para liberar a vaga.",
  "limit": 25
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar os tipos de evento

GET/v1/webhooks/event-types

Os tipos de evento que a Luna entrega, e que eventTypes aceita no cadastro e na alteração do endpoint. Cada item traz o type, que é o valor a enviar, uma frase que diz o que o evento é e o grupo a que pertence (group e groupLabel).

Autenticação
Chave de API
Escopo exigido
webhooks:read

Respostas

200Os tipos de evento que a Luna entrega, na ordem do contrato. O evento webhook.test não está na lista: ele só sai quando você o pede.
  • dataarray<object>obrigatório
  • data[].typestringobrigatório
    O tipo do evento, o valor que eventTypes aceita e que o campo event_type do evento traz.
  • data[].summarystringobrigatório
    Uma frase que diz o que o evento é.
  • data[].groupstringobrigatório
    O grupo do tipo, para agrupar a lista: messages, numbers, accounts, templates, links ou system. Um tipo novo cai no grupo do seu prefixo, ou em system.Valores: messages numbers accounts templates links system
  • data[].groupLabelstringobrigatório
    O nome do grupo, em português.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Consultar o endpoint de webhook

GET/v1/webhooks/endpoints/{id}

A configuração do endpoint.

Autenticação
Chave de API
Escopo exigido
webhooks:read

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Respostas

200A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.
  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.
  • urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • createdAtstringobrigatório
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringobrigatório
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullobrigatório
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanobrigatório
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullobrigatório
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>obrigatório
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>obrigatório
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>obrigatório
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>obrigatório
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullobrigatório
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullobrigatório
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullobrigatório
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringobrigatório
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Valores: ok failing paused never_delivered
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Alterar o endpoint de webhook

PATCH/v1/webhooks/endpoints/{id}

Muda a URL, pausa ou retoma o endpoint, ou troca os tipos de evento que ele recebe. Envie url, paused, eventTypes, externalIds, phoneNumberIds, headers ou qualquer combinação: um corpo sem nenhum deles responde 400.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Corpo da requisição

application/json · obrigatório

  • urlstringopcional
    A URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo.até 2048 caracteres
  • pausedbooleanopcional
    true pausa o endpoint: os eventos que ocorrerem enquanto ele estiver pausado não são entregues, nem depois. false o retoma, e ele passa a receber os eventos a partir desse momento.
  • eventTypesarray<string>opcional
    Troca a lista de tipos que o endpoint recebe: a lista enviada substitui a anterior. Lista vazia volta a receber todos. O que ocorreu antes da troca e foi filtrado não é entregue depois.até 30 itens
  • externalIdsarray<string>opcional
    Troca a lista de clientes de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Vale daí em diante.até 100 itens
  • phoneNumberIdsarray<string>opcional
    Troca a lista de números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Aceita o UUID da Luna ou o id da Meta.até 100 itens
  • headersobjectopcional
    Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos.

Respostas

200A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.
  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.
  • urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • createdAtstringobrigatório
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringobrigatório
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullobrigatório
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanobrigatório
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullobrigatório
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>obrigatório
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>obrigatório
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>obrigatório
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>obrigatório
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullobrigatório
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullobrigatório
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullobrigatório
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringobrigatório
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Valores: ok failing paused never_delivered
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Remover o endpoint de webhook

DELETE/v1/webhooks/endpoints/{id}

Remove o endpoint. A resposta é 204, e o endpoint deixa de receber eventos.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Respostas

204Sem conteúdo: a operação foi feita e a resposta não tem corpo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar as entregas do endpoint

GET/v1/webhooks/endpoints/{id}/deliveries

O histórico das tentativas de entrega ao endpoint nos últimos 7 dias, da mais recente à mais antiga: eventId, eventType, status, httpStatus (nulo quando o seu servidor não respondeu), durationMs, attempt e at. Filtros: status (success ou failed), eventType e since. Não traz o corpo enviado nem o que o seu servidor respondeu.

Autenticação
Chave de API
Escopo exigido
webhooks:read

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Parâmetros de consulta

  • limitintegeropcional
    Quantos itens trazer. Padrão 50, máximo 100, igual para todos.mínimo 1 · máximo 100
  • statusstringopcional
    success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta.Valores: success failed
  • eventTypestringopcional
    Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types).Valores: message.received message.status contact.identity_changed contact.preferences_changed backlog.dropped history_sync.deadline_approaching message.echo template.status number.connected number.payment_required number.payment_resolved account.restricted account.violation account.disabled account.reinstated account.update account.limit_changed number.disconnected number.quality_changed number.display_name_reviewed number.credential_expiring account.alert number.action_required number.action_resolved onboarding.link.completed onboarding.link.opened onboarding.link.failed onboarding.link.expired template.category template.quality
  • sincestring (date-time) | string (date)opcional
    Só as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias.
  • cursorstringopcional
    O nextCursor da página anterior. Omita na primeira.até 256 caracteres

Respostas

200O histórico de entregas do endpoint nos últimos 7 dias, uma linha por tentativa. Não traz o corpo enviado nem o que o seu servidor respondeu: só o status.
  • dataarray<object>obrigatório
    As tentativas desta página, da mais recente à mais antiga.
  • data[].idstring (uuid)obrigatório
    O identificador desta tentativa.
  • data[].eventIdstringobrigatório
    O event_id do evento, o mesmo que o seu servidor recebeu no corpo. Tentativas do mesmo evento repetem o eventId.
  • data[].eventTypestringobrigatório
    O tipo do evento.
  • data[].statusstringobrigatório
    success quando o seu servidor respondeu 2xx; failed no resto.Valores: success failed
  • data[].httpStatusinteger | nullobrigatório
    O status HTTP que o seu servidor devolveu. Nulo quando ele não respondeu (tempo esgotado, conexão recusada, endereço recusado).
  • data[].durationMsintegerobrigatório
    Quanto a chamada levou, em milissegundos.
  • data[].attemptintegerobrigatório
    A tentativa de entrega deste evento, a primeira é 1.
  • data[].atstringobrigatório
    Quando a tentativa aconteceu, em UTC.
  • nextCursorstring | nullobrigatório
    Mande este valor em cursor para pegar a página seguinte. Nulo é o fim. Não existe total: para saber quantas há, pagine até o fim.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Enviar um evento de teste

POST/v1/webhooks/endpoints/{id}/test

Envia UM evento webhook.test ao endpoint, agora, e devolve o resultado na própria resposta. O evento sai assinado, com os mesmos cabeçalhos, a mesma assinatura e as mesmas defesas de destino de uma entrega real, então um teste que passa prova que a URL e a verificação da assinatura funcionam. Com eventType no corpo, o evento é um exemplo daquele tipo, com corpo de mentira e test: true no envelope.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Corpo da requisição

application/json · obrigatório

  • eventTypestringopcional
    Um tipo de GET /v1/webhooks/event-types. A Luna entrega ao endpoint um exemplo desse tipo, com corpo de mentira (identificadores que não existem) e test: true no envelope, para você exercitar o seu código sem esperar o evento de verdade. Ausente, o teste é o webhook.test de sempre. O exemplo não passa por nenhum número seu.Valores: message.received message.status contact.identity_changed contact.preferences_changed backlog.dropped history_sync.deadline_approaching message.echo template.status number.connected number.payment_required number.payment_resolved account.restricted account.violation account.disabled account.reinstated account.update account.limit_changed number.disconnected number.quality_changed number.display_name_reviewed number.credential_expiring account.alert number.action_required number.action_resolved onboarding.link.completed onboarding.link.opened onboarding.link.failed onboarding.link.expired template.category template.quality

Respostas

200O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.
  • deliveredbooleanobrigatório
    true quando o seu servidor respondeu 2xx. É o mesmo critério de uma entrega real.
  • statusCodeinteger | nullobrigatório
    O status HTTP que o seu servidor devolveu, ou null quando não houve resposta.
  • durationMsintegerobrigatório
    Quanto tempo a chamada levou, em milissegundos.
  • failurestring | nullobrigatório
    Por que não foi entregue, ou null quando foi. timeout: o servidor não respondeu a tempo. connection: não foi possível conectar (DNS, TLS ou porta fechada). destination_not_allowed: a URL deixou de apontar para um endereço público. response_too_large: a resposta passou do tamanho que a Luna lê. http_status: o servidor respondeu, mas com status fora de 2xx, inclusive redirecionamento, que a Luna não segue; o status vem em statusCode.Valores: timeout connection destination_not_allowed response_too_large http_status
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Rotacionar o segredo de assinatura

POST/v1/webhooks/endpoints/{id}/rotacionar

Emite um segredo novo e devolve ele uma vez. Guarde-o agora, como no cadastro.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.

Corpo da requisição

application/json · obrigatório

  • revokePreviousbooleanopcional
    Com true, o segredo anterior deixa de valer no mesmo instante, em vez de seguir válido por sete dias. Use quando o segredo anterior vazou. As entregas que já saíram assinadas só com ele falham na verificação do seu lado.

Respostas

200O endpoint com o segredo novo. O anterior continua válido até previousSecretExpiresAt, então você pode trocar a configuração do seu lado sem pressa e sem perder entrega.
  • idstring (uuid)obrigatório
    O identificador do endpoint, devolvido no cadastro.
  • urlstringobrigatório
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteres
  • createdAtstringobrigatório
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringobrigatório
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullobrigatório
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanobrigatório
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullobrigatório
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>obrigatório
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>obrigatório
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>obrigatório
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>obrigatório
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullobrigatório
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullobrigatório
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullobrigatório
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringobrigatório
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Valores: ok failing paused never_delivered
  • secretstringobrigatório
    O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
Tipo de conteúdo não lidoJSON
{
  "error": "unsupported_media_type",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Envie o corpo como application/json."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Listar as entregas que falharam definitivamente

GET/v1/webhooks/dlq

Os eventos que a Luna tentou entregar ao seu endpoint e desistiu, do mais recente ao mais antigo, cada um com o número, o rótulo do cliente, as tentativas, o último status HTTP e o que se pode fazer com ele (allowedActions). Filtros: endpointId, externalId e requeued.

Autenticação
Chave de API
Escopo exigido
webhooks:read

Parâmetros de consulta

  • cursorstringopcional
    O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página.
  • limitintegeropcional
    Quantos itens trazer nesta página. Máximo 100, igual para todos.mínimo 1 · máximo 100 · padrão: 50
  • endpointIdstring (uuid)opcional
    Só os itens deste endpoint.
  • externalIdstringopcional
    Só os itens dos números deste cliente seu (externalId do número). Igualdade exata; um rótulo sem item devolve lista vazia.1 a 128 caracteres
  • requeuedstringopcional
    true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions).Valores: true false

Respostas

200Uma página da fila de rejeitados. Sem total e sem contagem: a Luna não soma entregas, e nenhum número desta resposta alimenta cobrança. attempts e lastHttpStatus descrevem UMA entrega que falhou, e não um agregado.
  • itemsarray<object>obrigatório
    Os itens desta página, do mais recente ao mais antigo.
  • items[].idstring (uuid)obrigatório
    O identificador deste item na fila de rejeitados.
  • items[].endpointIdstring (uuid)obrigatório
    O endpoint para o qual a entrega falhou.
  • items[].eventTypestringobrigatório
    O tipo do evento que não foi entregue.Valores: message.received message.status message.echo template.status number.payment_required number.payment_resolved account.restricted account.violation account.disabled account.reinstated account.update account.limit_changed number.disconnected number.quality_changed template.category template.quality number.credential_expiring account.alert contact.identity_changed contact.preferences_changed
  • items[].wamidstring | nullobrigatório
    O identificador da mensagem na Meta, o mesmo que o evento carrega. Nulo em todos os tipos que não são de mensagem (template.*, number.* e account.*), que não têm mensagem.
  • items[].rejectedAtstringobrigatório
    Quando a plataforma desistiu de tentar entregar este evento, em UTC.
  • items[].failureReasonstringobrigatório
    A classe da última falha. http_4xx é o seu servidor tendo entendido e recusado; http_5xx é ele tendo aceitado e quebrado; timeout é ele não ter respondido a tempo; conexao é não ter sido possível estabelecer a conexão; destino_recusado é a URL ter deixado de apontar para um endereço público; reenvio_pedido não é falha: é um reenvio que você mesmo pediu em POST /v1/messages/{id}/replay, e já nasce com requeuedAt preenchido.Valores: http_4xx http_5xx timeout conexao destino_recusado reenvio_pedido
  • items[].requeuedAtstring | nullobrigatório
    Quando este item foi re-enfileirado, ou null se ainda não foi. Pedir o re-enfileiramento de um item que já tem este campo preenchido responde 409, e não republica de novo.
  • items[].numberIdstring (uuid) | nullobrigatório
    O número da Luna por onde o evento passou, o mesmo id de GET /v1/numbers. Nulo nos eventos que não passam por número (template.*) e quando a mensagem já não está na Luna.
  • items[].externalIdstring | nullobrigatório
    O seu rótulo para o cliente dono desse número. Nulo quando não há número ou ele não tem rótulo.
  • items[].attemptsinteger | nullobrigatório
    Quantas vezes a Luna tentou entregar este evento antes de desistir. Nulo nos itens anteriores a este campo e nos reenvios pedidos por você (reenvio_pedido), que não são falha.
  • items[].lastHttpStatusinteger | nullobrigatório
    O status HTTP que o seu endpoint devolveu na última tentativa. Nulo quando ele não respondeu (tempo esgotado, conexão recusada) e nos itens anteriores a este campo.
  • items[].allowedActionsarray<string>obrigatório
    O que a sua conta pode fazer com o item agora: requeue (POST /v1/webhooks/dlq/{id}/reenfileirar), enquanto ele não foi re-enfileirado. Mostre o botão quando o verbo está na lista.
  • nextCursorstring | nullobrigatório
    Passe este valor em cursor para obter a página seguinte. null significa que esta é a última página. Não existe total: para saber quantos itens há, pagine até o fim.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}

Re-enfileirar uma entrega que falhou

POST/v1/webhooks/dlq/{id}/reenfileirar

Recoloca o evento na fila de entrega. A resposta é 202: o pedido foi registrado, e a entrega acontece de forma assíncrona.

Autenticação
Chave de API
Escopo exigido
webhooks:write

Parâmetros de caminho

  • idstring (uuid)obrigatório
    O identificador deste item na fila de rejeitados.

Respostas

202O item foi recolocado na fila de entrega. A entrega em si é assíncrona, como qualquer outra: se o seu endpoint ainda estiver fora do ar, ela será adiada e retentada pela mesma política de sempre.
  • idstring (uuid)obrigatório
    O identificador deste item na fila de rejeitados.
  • requeuedAtstringobrigatório
    O instante em que o re-enfileiramento foi registrado, em UTC.
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
Campo recusado, com o motivoJSON
{
  "error": "invalid_request",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisição inválida.",
  "campos": [
    {
      "campo": "text.body",
      "motivo": "Não pode ficar vazio."
    }
  ]
}
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
  • WWW-Authenticate Sempre Bearer.
Chave recusadaJSON
{
  "error": "unauthorized",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Credencial ausente ou inválida."
}
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
Escopo insuficienteJSON
{
  "error": "forbidden",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Esta chave não tem o escopo numbers:read, que esta operação exige. Crie uma chave com esse escopo (Integração, Chaves de API, no console) e use-a no lugar desta.",
  "requiredScope": "numbers:read"
}
Chave de teste numa rota que não é do modo de testeJSON
{
  "error": "test_key_not_allowed",
  "docsUrl": "https://lunahia.com.br/docs/modo-de-teste",
  "message": "Esta é uma chave de teste: ela só envia mensagem simulada (POST /v1/messages) e pede mensagem recebida simulada (POST /v1/test-mode/inbound-messages). Para esta operação, use uma chave de produção."
}
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
Não existe, ou não é seuJSON
{
  "error": "not_found",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Recurso não encontrado."
}
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
Item já re-enfileiradoJSON
{
  "error": "already_requeued",
  "docsUrl": "https://lunahia.com.br/docs/receber-eventos",
  "message": "Este item já foi re-enfileirado.",
  "reenfileiradoEm": "2026-10-06T12:00:00.000Z"
}
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
  • Retry-After Segundos a esperar antes de repetir.
Limite de requisiçõesJSON
{
  "error": "rate_limited",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Requisições demais. Tente novamente em instantes."
}
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.
IndisponívelJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}