Webhooks and events
Where Luna delivers what arrives at your number, the secret that signs those deliveries, and the event types, each with its schema and an example.
List webhook endpoints
GET/v1/webhooks/endpoints
The endpoints registered for this customer, newest first, with the endpoint limit and whether another can still be registered (limit and canCreate). Each endpoint carries deliveryStatus.
Responses
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>requireddata[].idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.data[].urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 charactersdata[].createdAtstringrequiredQuando o endpoint foi cadastrado, em UTC.data[].updatedAtstringrequiredQuando ele foi alterado pela última vez, em UTC.data[].previousSecretExpiresAtstring | nullrequiredEnquanto 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[].pausedbooleanrequiredtrue 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 | nullrequiredQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.data[].eventTypesarray<string>requiredOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.data[].externalIdsarray<string>requiredOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.data[].phoneNumberIdsarray<string>requiredOs 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>requiredOs 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 | nullrequiredQuando 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 | nullrequiredQuando 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 | nullrequiredO 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[].deliveryStatusstringrequiredA 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.Values:okfailingpausednever_deliveredlimitintegerrequiredO máximo de endpoints por cliente. É o mesmo para todos, e não depende do plano.canCreatebooleanrequiredfalse 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.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Register the webhook endpoint
POST/v1/webhooks/endpoints
Registers your server's URL and returns the secret that signs the deliveries. headers, optional, carries up to 5 own HTTP headers that Luna sends on every delivery (for a gateway that requires a fixed token); the values are secret and no response returns them.
Request body
urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characterseventTypesarray<string>optionalOs 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.up to 30 itemsexternalIdsarray<string>optionalOs 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.up to 100 itemsphoneNumberIdsarray<string>optionalOs 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.up to 100 itemsheadersobjectoptionalCabeç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.
Responses
201O endpoint recém-criado, com o segredo de assinatura.
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characterscreatedAtstringrequiredQuando o endpoint foi cadastrado, em UTC.updatedAtstringrequiredQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullrequiredEnquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.pausedbooleanrequiredtrue quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.pausedAtstring | nullrequiredQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>requiredOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>requiredOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>requiredOs 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>requiredOs 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 | nullrequiredQuando 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 | nullrequiredQuando 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 | nullrequiredO 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.deliveryStatusstringrequiredA 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.Values:okfailingpausednever_deliveredsecretstringrequiredO 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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"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
}415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}List the event types
GET/v1/webhooks/event-types
The event types Luna delivers, which eventTypes accepts when you register or update an endpoint. Each item carries the type, which is the value to send, a sentence that says what the event is, and the group it belongs to (group and groupLabel).
Responses
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>requireddata[].typestringrequiredO tipo do evento, o valor que eventTypes aceita e que o campo event_type do evento traz.data[].summarystringrequiredUma frase que diz o que o evento é.data[].groupstringrequiredO 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.Values:messagesnumbersaccountstemplateslinkssystemdata[].groupLabelstringrequiredO nome do grupo, em português.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Read the webhook endpoint
GET/v1/webhooks/endpoints/{id}
The endpoint's configuration.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Responses
200A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characterscreatedAtstringrequiredQuando o endpoint foi cadastrado, em UTC.updatedAtstringrequiredQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullrequiredEnquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.pausedbooleanrequiredtrue quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.pausedAtstring | nullrequiredQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>requiredOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>requiredOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>requiredOs 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>requiredOs 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 | nullrequiredQuando 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 | nullrequiredQuando 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 | nullrequiredO 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.deliveryStatusstringrequiredA 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.Values:okfailingpausednever_delivered
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Update the webhook endpoint
PATCH/v1/webhooks/endpoints/{id}
Changes the URL, pauses or resumes the endpoint, or changes the event types it receives. Send url, paused, eventTypes, externalIds, phoneNumberIds, headers or any combination: a body with none of them answers 400.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Request body
urlstringoptionalA URL nova. Passa pela mesma validação do cadastro: https e endereço público. O segredo de assinatura continua o mesmo.up to 2048 characterspausedbooleanoptionaltrue 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>optionalTroca 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.up to 30 itemsexternalIdsarray<string>optionalTroca 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.up to 100 itemsphoneNumberIdsarray<string>optionalTroca 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.up to 100 itemsheadersobjectoptionalCabeç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.
Responses
200A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characterscreatedAtstringrequiredQuando o endpoint foi cadastrado, em UTC.updatedAtstringrequiredQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullrequiredEnquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.pausedbooleanrequiredtrue quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.pausedAtstring | nullrequiredQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>requiredOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>requiredOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>requiredOs 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>requiredOs 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 | nullrequiredQuando 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 | nullrequiredQuando 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 | nullrequiredO 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.deliveryStatusstringrequiredA 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.Values:okfailingpausednever_delivered
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Remove the webhook endpoint
DELETE/v1/webhooks/endpoints/{id}
Removes the endpoint. The response is 204, and the endpoint stops receiving events.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Responses
204No content: the operation was done and the response has no body.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}List the endpoint's deliveries
GET/v1/webhooks/endpoints/{id}/deliveries
The delivery attempts to the endpoint over the last 7 days, newest first: eventId, eventType, status, httpStatus (null when your server did not answer), durationMs, attempt and at. Filters: status (success or failed), eventType and since. It does not carry the body sent or what your server answered.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Query parameters
limitintegeroptionalQuantos itens trazer. Padrão 50, máximo 100, igual para todos.minimum 1 · maximum 100statusstringoptionalsuccess: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta.Values:successfailedeventTypestringoptionalSó as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types).Values: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)optionalSó as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias.cursorstringoptionalO nextCursor da página anterior. Omita na primeira.up to 256 characters
Responses
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>requiredAs tentativas desta página, da mais recente à mais antiga.data[].idstring (uuid)requiredO identificador desta tentativa.data[].eventIdstringrequiredO event_id do evento, o mesmo que o seu servidor recebeu no corpo. Tentativas do mesmo evento repetem o eventId.data[].eventTypestringrequiredO tipo do evento.data[].statusstringrequiredsuccess quando o seu servidor respondeu 2xx; failed no resto.Values:successfaileddata[].httpStatusinteger | nullrequiredO status HTTP que o seu servidor devolveu. Nulo quando ele não respondeu (tempo esgotado, conexão recusada, endereço recusado).data[].durationMsintegerrequiredQuanto a chamada levou, em milissegundos.data[].attemptintegerrequiredA tentativa de entrega deste evento, a primeira é 1.data[].atstringrequiredQuando a tentativa aconteceu, em UTC.nextCursorstring | nullrequiredMande 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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Send a test event
POST/v1/webhooks/endpoints/{id}/test
Sends ONE webhook.test event to the endpoint, now, and returns the result in the response itself. The event goes out signed, with the same headers, the same signature and the same destination defenses as a real delivery, so a test that passes proves that the URL and signature verification work. With eventType in the body, the event is an example of that type, with a made-up body and test: true in the envelope.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Request body
eventTypestringoptionalUm 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.Values: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
Responses
200O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.
deliveredbooleanrequiredtrue quando o seu servidor respondeu 2xx. É o mesmo critério de uma entrega real.statusCodeinteger | nullrequiredO status HTTP que o seu servidor devolveu, ou null quando não houve resposta.durationMsintegerrequiredQuanto tempo a chamada levou, em milissegundos.failurestring | nullrequiredPor 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.Values:timeoutconnectiondestination_not_allowedresponse_too_largehttp_status
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Rotate the signing secret
POST/v1/webhooks/endpoints/{id}/rotacionar
Mints a new secret and returns it once. Store it now, as on registration.
Path parameters
idstring (uuid)requiredO identificador do endpoint, devolvido no cadastro.
Request body
revokePreviousbooleanoptionalCom 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.
Responses
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)requiredO identificador do endpoint, devolvido no cadastro.urlstringrequiredA URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characterscreatedAtstringrequiredQuando o endpoint foi cadastrado, em UTC.updatedAtstringrequiredQuando ele foi alterado pela última vez, em UTC.previousSecretExpiresAtstring | nullrequiredEnquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.pausedbooleanrequiredtrue quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.pausedAtstring | nullrequiredQuando o endpoint foi pausado, em UTC, ou null se ele está ativo.eventTypesarray<string>requiredOs tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.externalIdsarray<string>requiredOs clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.phoneNumberIdsarray<string>requiredOs 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>requiredOs 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 | nullrequiredQuando 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 | nullrequiredQuando 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 | nullrequiredO 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.deliveryStatusstringrequiredA 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.Values:okfailingpausednever_deliveredsecretstringrequiredO 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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}415The body came with a content-type the route does not read. Send application/json, or multipart/form-data on the file routes.
{
"error": "unsupported_media_type",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Envie o corpo como application/json."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}List deliveries that failed for good
GET/v1/webhooks/dlq
The events Luna tried to deliver to your endpoint and gave up on, newest first, each with the number, the customer label, the attempts, the last HTTP status and what can be done with it (allowedActions). Filters: endpointId, externalId and requeued.
Query parameters
cursorstringoptionalO cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página.limitintegeroptionalQuantos itens trazer nesta página. Máximo 100, igual para todos.minimum 1 · maximum 100 · default: 50endpointIdstring (uuid)optionalSó os itens deste endpoint.externalIdstringoptionalSó os itens dos números deste cliente seu (externalId do número). Igualdade exata; um rótulo sem item devolve lista vazia.1 to 128 charactersrequeuedstringoptionaltrue: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions).Values:truefalse
Responses
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>requiredOs itens desta página, do mais recente ao mais antigo.items[].idstring (uuid)requiredO identificador deste item na fila de rejeitados.items[].endpointIdstring (uuid)requiredO endpoint para o qual a entrega falhou.items[].eventTypestringrequiredO tipo do evento que não foi entregue.Values: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 | nullrequiredO 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[].rejectedAtstringrequiredQuando a plataforma desistiu de tentar entregar este evento, em UTC.items[].failureReasonstringrequiredA 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.Values:http_4xxhttp_5xxtimeoutconexaodestino_recusadoreenvio_pedidoitems[].requeuedAtstring | nullrequiredQuando 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) | nullrequiredO 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 | nullrequiredO 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 | nullrequiredQuantas 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 | nullrequiredO 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>requiredO 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 | nullrequiredPasse 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.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}Requeue a failed delivery
POST/v1/webhooks/dlq/{id}/reenfileirar
Puts the event back on the delivery queue. The response is 202: the request was recorded, and delivery happens asynchronously.
Path parameters
idstring (uuid)requiredO identificador deste item na fila de rejeitados.
Responses
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)requiredO identificador deste item na fila de rejeitados.requeuedAtstringrequiredO instante em que o re-enfileiramento foi registrado, em UTC.
400The body, query or identifier does not match the contract. Each item of campos gives the field and the reason, and the value you sent never comes back. Repeating the same request repeats the refusal.
{
"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."
}
]
}401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
WWW-AuthenticateAlways Bearer.
{
"error": "unauthorized",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Credencial ausente ou inválida."
}403The key lacks the scope the route requires. On a route that opens a number connection, also when the account cannot connect yet (connection_not_released). On the routes that write or send, also when the account is suspended: trial_expired (the free trial ended) or account_blocked (Helsen blocked the account). Suspension does not touch receiving: what arrives is still delivered to your webhook. A test key (mode test) only uses POST /v1/messages and POST /v1/test-mode/inbound-messages; on every other route it receives 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."
}404The resource does not exist, or is not yours. The two answers are identical, byte for byte.
{
"error": "not_found",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Recurso não encontrado."
}409The request is well formed, but the resource state does not allow it. The error field says which case it is.
{
"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"
}429Too many requests, or a full queue. Wait the time in the Retry-After header and repeat. For POST /v1/messages, repeat with the same Idempotency-Key.
Retry-AfterSeconds to wait before repeating.
{
"error": "rate_limited",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Requisições demais. Tente novamente em instantes."
}503The platform cannot serve right now. Repeat after a few moments, with the same Idempotency-Key when there is one.
{
"error": "unavailable",
"docsUrl": "https://lunahia.com.br/docs/erros",
"message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}