LunaDocs

Loading search...

PortuguêsSign in to the console
On this page

Webhooks and events

Use with AI

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.

Webhook events

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.

Authentication
API key
Required scope
webhooks:read

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>required
  • data[].idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.
  • data[].urlstringrequired
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characters
  • data[].createdAtstringrequired
    Quando o endpoint foi cadastrado, em UTC.
  • data[].updatedAtstringrequired
    Quando ele foi alterado pela última vez, em UTC.
  • data[].previousSecretExpiresAtstring | nullrequired
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • data[].pausedbooleanrequired
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • data[].pausedAtstring | nullrequired
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • data[].eventTypesarray<string>required
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • data[].externalIdsarray<string>required
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • data[].phoneNumberIdsarray<string>required
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • data[].headerNamesarray<string>required
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • data[].lastDeliveryAtstring | nullrequired
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • data[].lastFailureAtstring | nullrequired
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • data[].lastHttpStatusinteger | nullrequired
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • data[].deliveryStatusstringrequired
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Values: ok failing paused never_delivered
  • limitintegerrequired
    O máximo de endpoints por cliente. É o mesmo para todos, e não depende do plano.
  • canCreatebooleanrequired
    false quando você já chegou ao limite: POST /v1/webhooks/endpoints responderia 409. Remover um endpoint libera a vaga. A tela mostra o botão de cadastrar por este campo.
401The key is missing, malformed, nonexistent, expired or revoked. The body is always the same, without saying which.
  • WWW-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Request body

application/json · required

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

Responses

201O endpoint recém-criado, com o segredo de assinatura.
  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.
  • urlstringrequired
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characters
  • createdAtstringrequired
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringrequired
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullrequired
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanrequired
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullrequired
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>required
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>required
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>required
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>required
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullrequired
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullrequired
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullrequired
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringrequired
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Values: ok failing paused never_delivered
  • secretstringrequired
    O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo.
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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Endpoint limitJSON
{
  "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.
Content type not readJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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).

Authentication
API key
Required scope
webhooks:read

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>required
  • data[].typestringrequired
    O tipo do evento, o valor que eventTypes aceita e que o campo event_type do evento traz.
  • data[].summarystringrequired
    Uma frase que diz o que o evento é.
  • data[].groupstringrequired
    O grupo do tipo, para agrupar a lista: messages, numbers, accounts, templates, links ou system. Um tipo novo cai no grupo do seu prefixo, ou em system.Values: messages numbers accounts templates links system
  • data[].groupLabelstringrequired
    O 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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:read

Path parameters

  • idstring (uuid)required
    O 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)required
    O identificador do endpoint, devolvido no cadastro.
  • urlstringrequired
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characters
  • createdAtstringrequired
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringrequired
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullrequired
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanrequired
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullrequired
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>required
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>required
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>required
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>required
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullrequired
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullrequired
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullrequired
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringrequired
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Values: ok failing paused never_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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.

Request body

application/json · required

  • urlstringoptional
    A 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 characters
  • pausedbooleanoptional
    true pausa o endpoint: os eventos que ocorrerem enquanto ele estiver pausado não são entregues, nem depois. false o retoma, e ele passa a receber os eventos a partir desse momento.
  • eventTypesarray<string>optional
    Troca a lista de tipos que o endpoint recebe: a lista enviada substitui a anterior. Lista vazia volta a receber todos. O que ocorreu antes da troca e foi filtrado não é entregue depois.up to 30 items
  • externalIdsarray<string>optional
    Troca a lista de clientes de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Vale daí em diante.up to 100 items
  • phoneNumberIdsarray<string>optional
    Troca a lista de números de que o endpoint recebe eventos: a lista enviada substitui a anterior, e lista vazia volta a receber de todos. Aceita o UUID da Luna ou o id da Meta.up to 100 items
  • headersobjectoptional
    Cabeçalhos HTTP que a Luna envia em cada entrega a este endpoint, como { "X-Token": "valor" }, até 5. Para quem tem um gateway que exige um token fixo. Os valores são segredo: ficam cifrados, e nenhuma resposta os devolve, só os nomes (headerNames). Não valem os de transporte (content-type, host, content-length e afins) nem os x-luna-*. O valor tem até 1024 caracteres ASCII visíveis. No PATCH, o objeto enviado substitui o anterior, e {} remove todos.

Responses

200A configuração do endpoint. O segredo NÃO vem aqui: ele sai uma vez, no cadastro e na rotação.
  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.
  • urlstringrequired
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characters
  • createdAtstringrequired
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringrequired
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullrequired
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanrequired
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullrequired
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>required
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>required
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>required
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>required
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullrequired
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullrequired
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullrequired
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringrequired
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Values: ok failing paused never_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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O 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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:read

Path parameters

  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.

Query parameters

  • limitintegeroptional
    Quantos itens trazer. Padrão 50, máximo 100, igual para todos.minimum 1 · maximum 100
  • statusstringoptional
    success: só as tentativas que o seu servidor aceitou (2xx). failed: só as que falharam, com outro status ou sem resposta.Values: success failed
  • eventTypestringoptional
    Só as tentativas de eventos deste tipo (um valor de GET /v1/webhooks/event-types).Values: message.received message.status contact.identity_changed contact.preferences_changed backlog.dropped history_sync.deadline_approaching message.echo template.status number.connected number.payment_required number.payment_resolved account.restricted account.violation account.disabled account.reinstated account.update account.limit_changed number.disconnected number.quality_changed number.display_name_reviewed number.credential_expiring account.alert number.action_required number.action_resolved onboarding.link.completed onboarding.link.opened onboarding.link.failed onboarding.link.expired template.category template.quality
  • sincestring (date-time) | string (date)optional
    Só as tentativas deste instante em diante (ISO 8601, ou a data pura, que vale meia-noite UTC). O histórico guarda 7 dias.
  • cursorstringoptional
    O 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>required
    As tentativas desta página, da mais recente à mais antiga.
  • data[].idstring (uuid)required
    O identificador desta tentativa.
  • data[].eventIdstringrequired
    O event_id do evento, o mesmo que o seu servidor recebeu no corpo. Tentativas do mesmo evento repetem o eventId.
  • data[].eventTypestringrequired
    O tipo do evento.
  • data[].statusstringrequired
    success quando o seu servidor respondeu 2xx; failed no resto.Values: success failed
  • data[].httpStatusinteger | nullrequired
    O status HTTP que o seu servidor devolveu. Nulo quando ele não respondeu (tempo esgotado, conexão recusada, endereço recusado).
  • data[].durationMsintegerrequired
    Quanto a chamada levou, em milissegundos.
  • data[].attemptintegerrequired
    A tentativa de entrega deste evento, a primeira é 1.
  • data[].atstringrequired
    Quando a tentativa aconteceu, em UTC.
  • nextCursorstring | nullrequired
    Mande este valor em cursor para pegar a página seguinte. Nulo é o fim. Não existe total: para saber quantas há, pagine até o fim.
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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.

Request body

application/json · required

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

Responses

200O resultado do evento de teste. O corpo que o seu servidor respondeu não volta aqui, de propósito.
  • deliveredbooleanrequired
    true quando o seu servidor respondeu 2xx. É o mesmo critério de uma entrega real.
  • statusCodeinteger | nullrequired
    O status HTTP que o seu servidor devolveu, ou null quando não houve resposta.
  • durationMsintegerrequired
    Quanto tempo a chamada levou, em milissegundos.
  • failurestring | nullrequired
    Por que não foi entregue, ou null quando foi. timeout: o servidor não respondeu a tempo. connection: não foi possível conectar (DNS, TLS ou porta fechada). destination_not_allowed: a URL deixou de apontar para um endereço público. response_too_large: a resposta passou do tamanho que a Luna lê. http_status: o servidor respondeu, mas com status fora de 2xx, inclusive redirecionamento, que a Luna não segue; o status vem em statusCode.Values: timeout connection destination_not_allowed response_too_large http_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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O identificador do endpoint, devolvido no cadastro.

Request body

application/json · required

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

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)required
    O identificador do endpoint, devolvido no cadastro.
  • urlstringrequired
    A URL do seu servidor que vai receber os eventos. Precisa ser https e precisa resolver para um endereço público.up to 2048 characters
  • createdAtstringrequired
    Quando o endpoint foi cadastrado, em UTC.
  • updatedAtstringrequired
    Quando ele foi alterado pela última vez, em UTC.
  • previousSecretExpiresAtstring | nullrequired
    Enquanto este instante estiver no futuro, as entregas carregam duas assinaturas: a do segredo novo e a do anterior. Depois dele, só a do novo.
  • pausedbooleanrequired
    true quando o endpoint está pausado. Pausado, ele não recebe eventos novos, e o que ocorrer durante a pausa não é entregue depois.
  • pausedAtstring | nullrequired
    Quando o endpoint foi pausado, em UTC, ou null se ele está ativo.
  • eventTypesarray<string>required
    Os tipos de evento que o endpoint recebe. Lista vazia quer dizer todos.
  • externalIdsarray<string>required
    Os clientes (externalId) de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • phoneNumberIdsarray<string>required
    Os números, em ids da Meta (o phone_number_id dos eventos), de que o endpoint recebe eventos. Lista vazia quer dizer todos.
  • headerNamesarray<string>required
    Os nomes dos cabeçalhos próprios que a Luna envia a este endpoint (headers no cadastro). Só os nomes: os valores são segredo e nenhuma resposta os devolve. Lista vazia: nenhum.
  • lastDeliveryAtstring | nullrequired
    Quando o endpoint aceitou uma entrega pela última vez, em UTC, ou null se nenhuma foi aceita ainda. É o instante da última, e não um histórico: a Luna não conta entregas. O histórico tentativa por tentativa está em GET /v1/webhooks/endpoints/{id}/deliveries.
  • lastFailureAtstring | nullrequired
    Quando uma entrega a este endpoint falhou pela última vez, em UTC, ou null se nenhuma falhou ainda. Vale a mesma ressalva: é um instante, e não um histórico.
  • lastHttpStatusinteger | nullrequired
    O status HTTP da última tentativa de entrega, ou null quando ainda não houve tentativa ou quando a última não teve resposta (tempo esgotado, conexão recusada). Gravado no máximo a cada 10 segundos por endpoint.
  • deliveryStatusstringrequired
    A situação das entregas, decidida pela API: paused (o endpoint está pausado), failing (a última entrega falhou e veio depois da última que deu certo), never_delivered (nenhuma entrega foi tentada ainda) ou ok. Vale a mesma ressalva dos instantes: é a última situação, e não um histórico.Values: ok failing paused never_delivered
  • secretstringrequired
    O segredo que assina as entregas para este endpoint. Ele aparece nesta resposta e em mais nenhuma: guarde-o agora. A Luna guarda apenas a forma cifrada dele, e nenhuma rota o devolve. Se você o perder, rotacione para receber um novo.
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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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.
Content type not readJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:read

Query parameters

  • cursorstringoptional
    O cursor devolvido em nextCursor pela chamada anterior. Omita na primeira página.
  • limitintegeroptional
    Quantos itens trazer nesta página. Máximo 100, igual para todos.minimum 1 · maximum 100 · default: 50
  • endpointIdstring (uuid)optional
    Só os itens deste endpoint.
  • externalIdstringoptional
    Só 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 characters
  • requeuedstringoptional
    true: só os já re-enfileirados. false: só os que ainda podem ser (os que têm requeue em allowedActions).Values: true false

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>required
    Os itens desta página, do mais recente ao mais antigo.
  • items[].idstring (uuid)required
    O identificador deste item na fila de rejeitados.
  • items[].endpointIdstring (uuid)required
    O endpoint para o qual a entrega falhou.
  • items[].eventTypestringrequired
    O tipo do evento que não foi entregue.Values: message.received message.status message.echo template.status number.payment_required number.payment_resolved account.restricted account.violation account.disabled account.reinstated account.update account.limit_changed number.disconnected number.quality_changed template.category template.quality number.credential_expiring account.alert contact.identity_changed contact.preferences_changed
  • items[].wamidstring | nullrequired
    O identificador da mensagem na Meta, o mesmo que o evento carrega. Nulo em todos os tipos que não são de mensagem (template.*, number.* e account.*), que não têm mensagem.
  • items[].rejectedAtstringrequired
    Quando a plataforma desistiu de tentar entregar este evento, em UTC.
  • items[].failureReasonstringrequired
    A classe da última falha. http_4xx é o seu servidor tendo entendido e recusado; http_5xx é ele tendo aceitado e quebrado; timeout é ele não ter respondido a tempo; conexao é não ter sido possível estabelecer a conexão; destino_recusado é a URL ter deixado de apontar para um endereço público; reenvio_pedido não é falha: é um reenvio que você mesmo pediu em POST /v1/messages/{id}/replay, e já nasce com requeuedAt preenchido.Values: http_4xx http_5xx timeout conexao destino_recusado reenvio_pedido
  • items[].requeuedAtstring | nullrequired
    Quando este item foi re-enfileirado, ou null se ainda não foi. Pedir o re-enfileiramento de um item que já tem este campo preenchido responde 409, e não republica de novo.
  • items[].numberIdstring (uuid) | nullrequired
    O número da Luna por onde o evento passou, o mesmo id de GET /v1/numbers. Nulo nos eventos que não passam por número (template.*) e quando a mensagem já não está na Luna.
  • items[].externalIdstring | nullrequired
    O seu rótulo para o cliente dono desse número. Nulo quando não há número ou ele não tem rótulo.
  • items[].attemptsinteger | nullrequired
    Quantas vezes a Luna tentou entregar este evento antes de desistir. Nulo nos itens anteriores a este campo e nos reenvios pedidos por você (reenvio_pedido), que não são falha.
  • items[].lastHttpStatusinteger | nullrequired
    O status HTTP que o seu endpoint devolveu na última tentativa. Nulo quando ele não respondeu (tempo esgotado, conexão recusada) e nos itens anteriores a este campo.
  • items[].allowedActionsarray<string>required
    O que a sua conta pode fazer com o item agora: requeue (POST /v1/webhooks/dlq/{id}/reenfileirar), enquanto ele não foi re-enfileirado. Mostre o botão quando o verbo está na lista.
  • nextCursorstring | nullrequired
    Passe este valor em cursor para obter a página seguinte. null significa que esta é a última página. Não existe total: para saber quantos itens há, pagine até o fim.
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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "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.

Authentication
API key
Required scope
webhooks:write

Path parameters

  • idstring (uuid)required
    O 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)required
    O identificador deste item na fila de rejeitados.
  • requeuedAtstringrequired
    O 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.
Field refused, with the reasonJSON
{
  "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-Authenticate Always Bearer.
Key refusedJSON
{
  "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.
Insufficient scopeJSON
{
  "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"
}
Test key on a route outside test modeJSON
{
  "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.
Does not exist, or is not yoursJSON
{
  "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.
Item already requeuedJSON
{
  "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-After Seconds to wait before repeating.
Request limitJSON
{
  "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.
UnavailableJSON
{
  "error": "unavailable",
  "docsUrl": "https://lunahia.com.br/docs/erros",
  "message": "Não foi possível concluir a operação agora. Tente novamente em instantes."
}