Webhooks e eventos
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.
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.
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óriodata[].idstring (uuid)obrigatórioO identificador do endpoint, devolvido no cadastro.data[].urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracteresdata[].createdAtstringobrigatórioQuando o endpoint foi cadastrado, em UTC.data[].updatedAtstringobrigatórioQuando ele foi alterado pela última vez, em UTC.data[].previousSecretExpiresAtstring | nullobrigatórioEnquanto 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óriotrue 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órioQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.data[].eventTypesarray<string>obrigatórioOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.data[].externalIdsarray<string>obrigatórioOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.data[].phoneNumberIdsarray<string>obrigatórioOs 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órioOs 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órioQuando 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órioQuando 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órioO 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órioA 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:okfailingpausednever_deliveredlimitintegerobrigatórioO máximo de endpoints por cliente. É o mesmo para todos, e não depende do plano.canCreatebooleanobrigatóriofalse 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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Corpo da requisição
urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caractereseventTypesarray<string>opcionalOs 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 itensexternalIdsarray<string>opcionalOs 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 itensphoneNumberIdsarray<string>opcionalOs 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 itensheadersobjectopcionalCabeç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órioO identificador do endpoint, devolvido no cadastro.urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracterescreatedAtstringobrigatórioQuando o endpoint foi cadastrado, em UTC.updatedAtstringobrigatórioQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullobrigatórioEnquanto 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óriotrue 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órioQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>obrigatórioOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>obrigatórioOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>obrigatórioOs 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órioOs 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órioQuando 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órioQuando 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órioO 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órioA 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:okfailingpausednever_deliveredsecretstringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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).
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óriodata[].typestringobrigatórioO tipo do evento, o valor que eventTypes aceita e que o campo event_type do evento traz.data[].summarystringobrigatórioUma frase que diz o que o evento é.data[].groupstringobrigatórioO 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:messagesnumbersaccountstemplateslinkssystemdata[].groupLabelstringobrigatórioO nome do grupo, em português.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
WWW-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO 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órioO identificador do endpoint, devolvido no cadastro.urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracterescreatedAtstringobrigatórioQuando o endpoint foi cadastrado, em UTC.updatedAtstringobrigatórioQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullobrigatórioEnquanto 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óriotrue 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órioQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>obrigatórioOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>obrigatórioOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>obrigatórioOs 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órioOs 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órioQuando 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órioQuando 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órioO 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órioA 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:okfailingpausednever_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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador do endpoint, devolvido no cadastro.
Corpo da requisição
urlstringopcionalA URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo.até 2048 caracterespausedbooleanopcionaltrue 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>opcionalTroca 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 itensexternalIdsarray<string>opcionalTroca 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 itensphoneNumberIdsarray<string>opcionalTroca 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 itensheadersobjectopcionalCabeç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órioO identificador do endpoint, devolvido no cadastro.urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracterescreatedAtstringobrigatórioQuando o endpoint foi cadastrado, em UTC.updatedAtstringobrigatórioQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullobrigatórioEnquanto 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óriotrue 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órioQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>obrigatórioOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>obrigatórioOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>obrigatórioOs 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órioOs 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órioQuando 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órioQuando 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órioO 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órioA 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:okfailingpausednever_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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador do endpoint, devolvido no cadastro.
Parâmetros de consulta
limitintegeropcionalQuantos itens trazer. Padrão 50, máximo 100, igual para todos.mínimo 1 · máximo 100statusstringopcionalsuccess: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta.Valores:successfailedeventTypestringopcionalSó as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types).Valores:message.receivedmessage.statuscontact.identity_changedcontact.preferences_changedbacklog.droppedhistory_sync.deadline_approachingmessage.echotemplate.statusnumber.connectednumber.payment_requirednumber.payment_resolvedaccount.restrictedaccount.violationaccount.disabledaccount.reinstatedaccount.updateaccount.limit_changednumber.disconnectednumber.quality_changednumber.display_name_reviewednumber.credential_expiringaccount.alertnumber.action_requirednumber.action_resolvedonboarding.link.completedonboarding.link.openedonboarding.link.failedonboarding.link.expiredtemplate.categorytemplate.qualitysincestring (date-time) | string (date)opcionalSó as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias.cursorstringopcionalO 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órioAs tentativas desta página, da mais recente à mais antiga.data[].idstring (uuid)obrigatórioO identificador desta tentativa.data[].eventIdstringobrigatórioO event_id do evento, o mesmo que o seu servidor recebeu no corpo. Tentativas do mesmo evento repetem o eventId.data[].eventTypestringobrigatórioO tipo do evento.data[].statusstringobrigatóriosuccess quando o seu servidor respondeu 2xx; failed no resto.Valores:successfaileddata[].httpStatusinteger | nullobrigatórioO status HTTP que o seu servidor devolveu. Nulo quando ele não respondeu (tempo esgotado, conexão recusada, endereço recusado).data[].durationMsintegerobrigatórioQuanto a chamada levou, em milissegundos.data[].attemptintegerobrigatórioA tentativa de entrega deste evento, a primeira é 1.data[].atstringobrigatórioQuando a tentativa aconteceu, em UTC.nextCursorstring | nullobrigatórioMande 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador do endpoint, devolvido no cadastro.
Corpo da requisição
eventTypestringopcionalUm 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.receivedmessage.statuscontact.identity_changedcontact.preferences_changedbacklog.droppedhistory_sync.deadline_approachingmessage.echotemplate.statusnumber.connectednumber.payment_requirednumber.payment_resolvedaccount.restrictedaccount.violationaccount.disabledaccount.reinstatedaccount.updateaccount.limit_changednumber.disconnectednumber.quality_changednumber.display_name_reviewednumber.credential_expiringaccount.alertnumber.action_requirednumber.action_resolvedonboarding.link.completedonboarding.link.openedonboarding.link.failedonboarding.link.expiredtemplate.categorytemplate.quality
Respostas
200O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.
deliveredbooleanobrigatóriotrue quando o seu servidor respondeu 2xx. É o mesmo critério de uma entrega real.statusCodeinteger | nullobrigatórioO status HTTP que o seu servidor devolveu, ou null quando não houve resposta.durationMsintegerobrigatórioQuanto tempo a chamada levou, em milissegundos.failurestring | nullobrigatórioPor 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:timeoutconnectiondestination_not_allowedresponse_too_largehttp_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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO identificador do endpoint, devolvido no cadastro.
Corpo da requisição
revokePreviousbooleanopcionalCom 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órioO identificador do endpoint, devolvido no cadastro.urlstringobrigatórioA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.até 2048 caracterescreatedAtstringobrigatórioQuando o endpoint foi cadastrado, em UTC.updatedAtstringobrigatórioQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullobrigatórioEnquanto 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óriotrue 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órioQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>obrigatórioOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>obrigatórioOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>obrigatórioOs 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órioOs 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órioQuando 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órioQuando 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órioO 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órioA 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:okfailingpausednever_deliveredsecretstringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de consulta
cursorstringopcionalO cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página.limitintegeropcionalQuantos itens trazer nesta página. Máximo 100, igual para todos.mínimo 1 · máximo 100 · padrão: 50endpointIdstring (uuid)opcionalSó os itens deste endpoint.externalIdstringopcionalSó 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 caracteresrequeuedstringopcionaltrue: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions).Valores:truefalse
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órioOs itens desta página, do mais recente ao mais antigo.items[].idstring (uuid)obrigatórioO identificador deste item na fila de rejeitados.items[].endpointIdstring (uuid)obrigatórioO endpoint para o qual a entrega falhou.items[].eventTypestringobrigatórioO tipo do evento que não foi entregue.Valores:message.receivedmessage.statusmessage.echotemplate.statusnumber.payment_requirednumber.payment_resolvedaccount.restrictedaccount.violationaccount.disabledaccount.reinstatedaccount.updateaccount.limit_changednumber.disconnectednumber.quality_changedtemplate.categorytemplate.qualitynumber.credential_expiringaccount.alertcontact.identity_changedcontact.preferences_changeditems[].wamidstring | nullobrigatórioO 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órioQuando a plataforma desistiu de tentar entregar este evento, em UTC.items[].failureReasonstringobrigatórioA 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_4xxhttp_5xxtimeoutconexaodestino_recusadoreenvio_pedidoitems[].requeuedAtstring | nullobrigatórioQuando 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órioO 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órioO 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órioQuantas 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órioO 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órioO 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órioPasse 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"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.
Parâmetros de caminho
idstring (uuid)obrigatórioO 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órioO identificador deste item na fila de rejeitados.requeuedAtstringobrigatórioO 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.
{
"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-AuthenticateSempre Bearer.
{
"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.
{
"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"
}{
"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.
{
"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.
{
"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-AfterSegundos a esperar antes de repetir.
{
"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.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}