Documentação da API do usuário do Loomio

/api/user0 é a API voltada ao usuário para integrações com o Loomio. Ela usa a chave de API de uma conta de usuário, e todas as ações são realizadas em nome desse usuário.

As operações em grupos usam os vínculos de membro e as permissões de grupo do usuário da chave de API. Ser administrador da instância não amplia o acesso de uma chave de API a grupos ou conteúdos; use a API do servidor para administrar a instância.

Use a chave de API da conta de usuário do Loomio que realizará as ações. Uma conta exclusiva para o bot é útil quando uma integração não deve receber convites para enquetes nem notificações.

Usuários conectados podem encontrar sua chave de API e os IDs dos grupos na página de acesso à API.

Envie a chave de API em um cabeçalho Authorization: Bearer. Chaves de API em parâmetros de consulta são rejeitadas porque as URLs podem ser registradas por proxies e logs de acesso.

Authorization: Bearer YOUR_API_KEY

Os exemplos usam YOUR_API_KEY, o ID de grupo 123 e https://www.loomio.com/. Substitua esses valores pela sua chave de API, pelo ID do seu grupo e pela URL da sua instalação do Loomio.

Enviar corpos de requisição

Envie JSON com Content-Type: application/json. Os exemplos de cURL usam --json, que define esse cabeçalho automaticamente. Os endpoints de criação e edição de discussões, comentários e enquetes aceitam um objeto simples ou um objeto aninhado sob o nome do recurso, como {"poll": {...}}.

Envie arrays como arrays JSON, como "options": ["foo", "bar"]. Se você usar a codificação de formulário, os arrays precisam de nomes de campo com colchetes, como options[]=foo&options[]=bar; repetir options=foo&options=bar mantém apenas o último valor.

Verifique o status HTTP e o corpo da resposta após cada requisição. Uma falha de validação retorna 422 com um objeto errors; a criação bem-sucedida de uma enquete retorna a enquete em polls e suas opções em poll_options.

Resumo dos endpoints

Paginação

Discussões, grupos, vínculos de membros, enquetes, conversas, itens de conversas e webhooks aceitam limit (padrão 50) e offset (padrão 0). Grupos, itens de conversas e webhooks limitam limit a 500.

Aumente offset pelo número de registros principais retornados para obter a próxima página. meta.total é o total de registros correspondentes; os registros relacionados não contam para o tamanho da página.

Os relatórios de participação retornam todos os dados solicitados, e a busca retorna até 20 resultados. Nenhum dos dois oferece paginação.

Discussões, enquetes e vínculos de membros também aceitam os aliases legados per para limit e from para offset. Use limit e offset em novas integrações.

Registros relacionados

As respostas da API do usuário usam um formato composto: os registros principais vêm acompanhados de registros relacionados, como conversas, grupos, usuários, enquetes e reações. Isso permite que um cliente preencha um armazenamento local de registros com uma única requisição, mas pode incluir mais dados do que uma integração simples precisa.

Passe compact=1 para omitir registros relacionados volumosos de conversas, grupos, grupos principais, vínculos de membros, reações, tags e traduções. Os registros principais e os registros relacionados necessários para interpretar seu conteúdo continuam presentes.

curl 'https://www.loomio.com/api/user0/threads/123/items?compact=1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Para controlar diretamente as exclusões, passe exclude_types com os tipos de registro no singular, separados por espaços. Por exemplo, exclude_types=group reaction omite grupos e reações relacionados. Os valores comuns são topic, group, parent, membership, reaction, tag, translation, user, discussion, poll, poll_option, stance, stance_choice, outcome e topic_item. As exclusões se aplicam aos registros relacionados, não ao recurso principal solicitado pelo endpoint.

As respostas de coleções incluem meta.total quando há um tamanho exato definido para a coleção. O total é calculado antes da aplicação de limit e offset. Endpoints como o de busca, que retornam intencionalmente um conjunto limitado de resultados, omitem meta.total em vez de retornar null.

Comentários

Criar um comentário

Crie um comentário em uma discussão como o usuário da chave de API.

POST /api/user0/comments

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/comments \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "discussion_id": 123,
    "body": "example comment",
    "body_format": "md"
  }'

Editar um comentário

Edite um comentário como o usuário da chave de API. As mesmas permissões do Loomio se aplicam: o usuário deve ter permissão para editar esse comentário.

PATCH /api/user0/comments/:id

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/comments/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "body": "updated comment",
    "body_format": "md"
  }'

Excluir um comentário logicamente

Exclua um comentário logicamente como o usuário da chave de API. Isso descarta o comentário, oculta seu corpo e mantém seu registro.

DELETE /api/user0/comments/:id

Exemplo

curl https://www.loomio.com/api/user0/comments/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Discussões

Criar discussão

Crie uma discussão como o usuário da chave de API.

POST /api/user0/discussions

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/discussions \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example thread",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Exibir discussão

Obtenha uma discussão usando seu ID, um número inteiro, ou sua chave, uma string.

GET /api/user0/discussions/:id

Exemplo

curl https://www.loomio.com/api/user0/discussions/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar discussões

Liste as discussões de um grupo visíveis ao usuário da chave de API. Em um grupo visível publicamente, uma pessoa que não é membro pode listar suas discussões públicas; as discussões privadas continuam restritas aos usuários que podem lê-las no Loomio.

GET /api/user0/discussions

Parâmetros

Compatibilidade com versões anteriores: per e from são aceitos como aliases de limit e offset e continuarão funcionando.

Exemplo

curl 'https://www.loomio.com/api/user0/discussions?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Editar discussão

Edite uma discussão como o usuário da chave de API. As mesmas permissões do Loomio se aplicam: o usuário deve ter permissão para editar essa discussão.

PATCH /api/user0/discussions/:id

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/discussions/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated thread title",
    "description": "updated context",
    "description_format": "md"
  }'

Excluir uma discussão logicamente

Exclua uma discussão logicamente como o usuário da chave de API. Isso descarta a discussão e mantém seu registro.

DELETE /api/user0/discussions/:id

Exemplo

curl https://www.loomio.com/api/user0/discussions/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Grupos

Listar grupos

Retorna os grupos nos quais o usuário da chave de API tem um vínculo de membro ativo.

GET /api/user0/groups

curl 'https://www.loomio.com/api/user0/groups?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A resposta contém uma página de groups ordenada pelo ID do grupo em ordem crescente, com o total de grupos correspondentes em meta.total. Ela inclui grupos principais e subgrupos, inclusive grupos cuja assinatura não está ativa no momento. Verifique o campo enabled quando uma integração deve operar apenas em grupos habilitados.

Os principais campos de grupo incluem:

A resposta pode incluir configurações adicionais do grupo, registros relacionados de grupos principais e os vínculos de membro do usuário da API. Os clientes devem ignorar os campos que não usam.

Obter um grupo

Retorna um grupo visível ao usuário da chave de API.

GET /api/user0/groups/:id_or_key_or_handle

O identificador pode ser o ID numérico, a chave ou o identificador legível do grupo.

curl https://www.loomio.com/api/user0/groups/123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

curl https://www.loomio.com/api/user0/groups/example-group \
  -H 'Authorization: Bearer YOUR_API_KEY'

A resposta contém o grupo no array groups e usa os mesmos campos do endpoint de listagem. Uma requisição para um grupo que o usuário da chave de API não pode acessar retorna um erro de permissão.

Vínculos de membros

Listar vínculos de membros

Liste os vínculos de membros visíveis ao usuário da chave de API. Os membros do grupo podem consultar os nomes, IDs, títulos e funções dos membros. Os endereços de e-mail são incluídos apenas para a própria conta do usuário da chave de API ou quando esse usuário é administrador do grupo.

GET /api/user0/memberships

Parâmetros

Compatibilidade com versões anteriores: per e from são aceitos como aliases de limit e offset e continuarão funcionando.

A resposta contém uma página de memberships e os registros de users relacionados. meta.total é o número total de vínculos de membros visíveis no grupo antes da paginação.

Exemplo

curl 'https://www.loomio.com/api/user0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Gerenciar vínculos de membros

Envie uma lista de endereços de e-mail. Todos os novos endereços receberão um convite para o grupo. Ao contrário da listagem de vínculos de membros, esta operação exige permissão de administrador do grupo.

POST /api/user0/memberships

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ]
  }'

Se você passar remove_absent=1, todos os membros do grupo que não estiverem na lista serão removidos do grupo. Tenha cuidado: você pode remover todas as pessoas do seu grupo.

curl https://www.loomio.com/api/user0/memberships \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "person@example.com"
    ],
    "remove_absent": 1
  }'

Isso retorna um objeto com {added_emails: ["person@added.com"], removed_emails: ["person@removed.com"]}.

Relatório de participação

Retorne os mesmos dados agregados de participação usados pelo relatório de participação do Loomio.

GET /api/user0/reports

Parâmetros

Uma pessoa é delegada quando tem uma participação ativa como delegada em qualquer grupo selecionado. Suas contagens são agregadas em todos os grupos selecionados. As linhas dos delegados são retornadas mesmo quando todas as contagens de atividade são zero. As contagens abrangem conversas, comentários, enquetes, votos, conclusões e reações; elas não são taxas de participação nas votações. As linhas dos usuários também incluem cédulas de votação identificadas emitidas, usadas para votar e não usadas. As enquetes anônimas são excluídas de todas as contagens de votação por pessoa. all_votes_cast é verdadeiro somente quando pelo menos uma cédula foi emitida e todas as cédulas emitidas foram usadas para votar.

A API aplica as mesmas regras de visibilidade dos grupos que o relatório disponível no aplicativo. Uma chave da API do usuário não pode expor dados de relatório de grupos aos quais esse usuário não tem acesso.

Exemplo

curl 'https://www.loomio.com/api/user0/reports?section=users&group_scope=custom&group_ids=123&member_type=delegate&start_month=2026-01&end_month=2026-09' \
  -H 'Authorization: Bearer YOUR_API_KEY'

O array users contém linhas completas de atividade:

{
  "users": [
    {
      "id": 456,
      "name": "Ada Lovelace",
      "country": "NZ",
      "delegate": true,
      "threads": 2,
      "comments": 8,
      "polls": 1,
      "votes": 5,
      "votes_cast": 5,
      "votes_issued": 6,
      "votes_missed": 1,
      "all_votes_cast": false,
      "outcomes": 1,
      "reactions": 4
    }
  ]
}

Enquetes

Criar uma enquete

Crie uma enquete como o usuário da chave de API.

POST /api/user0/polls

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "example poll",
    "poll_type": "proposal",
    "options": [
      "agree",
      "disagree"
    ],
    "closing_at": "2026-09-01T12:00:00Z",
    "recipient_emails": [
      "person@example.com"
    ]
  }'

Criar um rascunho de enquete com muitas opções

Envie todos os nomes das opções no array options. Omitir closing_at cria uma enquete em elaboração com a votação desativada; isso não oculta a enquete das pessoas que podem ler sua conversa. Adicione um valor futuro para closing_at quando você estiver pronto para abrir a votação.

Adicione todos os nomes das suas opções ao array:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Meeting venue",
    "poll_type": "poll",
    "options": [
      "Town hall",
      "Library",
      "Community centre"
    ]
  }'

Criar uma enquete com opções detalhadas

Use options para uma lista de nomes ou poll_options_attributes quando cada opção precisar de um significado, uma pergunta para o motivo ou um ícone. Escolha um formato por requisição. Ambos os formatos funcionam em um corpo JSON sem aninhamento ou dentro de um objeto poll.

Cada objeto em poll_options_attributes aceita estes campos:

Crie uma proposta com rótulos e perguntas personalizados para as opções:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Should we adopt this proposal?",
    "poll_type": "proposal",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Support",
        "meaning": "I support adopting this proposal",
        "prompt": "What do you support about it?",
        "icon": "agree",
        "priority": 0
      },
      {
        "name": "Oppose",
        "meaning": "I would prefer another approach",
        "prompt": "What would you change?",
        "icon": "disagree",
        "priority": 1
      }
    ]
  }'

Para uma enquete comum, use o mesmo formato de opções detalhadas com um reason_prompt compartilhado na enquete:

curl https://www.loomio.com/api/user0/polls \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "title": "Choose a venue",
    "poll_type": "poll",
    "reason_prompt": "Why do you prefer this venue?",
    "stance_reason_required": "optional",
    "poll_options_attributes": [
      {
        "name": "Town hall",
        "meaning": "Central, accessible venue",
        "priority": 0
      },
      {
        "name": "Library",
        "meaning": "Smaller room with no hire fee",
        "priority": 1
      }
    ]
  }'

Estes exemplos omitem closing_at, portanto a votação permanece desativada até que uma data de encerramento futura seja definida.

Exibir enquete

Obtenha uma enquete usando seu ID, um inteiro, ou sua chave, uma string.

GET /api/user0/polls/:id

Exemplo

curl https://www.loomio.com/api/user0/polls/abc123 \
  -H 'Authorization: Bearer YOUR_API_KEY'

Listar enquetes

Liste as enquetes de um grupo visíveis ao usuário da chave de API, incluindo enquetes independentes e enquetes em discussões. Em um grupo visível publicamente, uma pessoa que não seja membro pode listar suas enquetes públicas; as enquetes privadas continuam restritas aos usuários que podem lê-las no Loomio. A resposta inclui a conclusão atual de cada enquete visível, então você pode usar status=closed para listar enquetes encerradas e ler suas conclusões, quando houver.

Para exibir o status da decisão junto às discussões, obtenha as discussões e enquetes do mesmo grupo, usando status=all para as enquetes, e faça a correspondência entre seus valores de topic_id. Obtenha todas as páginas usando limit e offset. Uma discussão pode ter várias enquetes, então escolha qual enquete determina o status exibido, por exemplo, a enquete criada mais recentemente. Um valor de closed_at diferente de null identifica uma enquete encerrada; um valor null em closing_at indica um rascunho. Quando uma enquete tem uma conclusão, seu current_outcome_id identifica um registro no array outcomes da resposta; faça a correspondência entre o poll_id desse registro e o id da enquete.

Para uma única discussão, você também pode ler os itens de sua conversa usando GET /api/user0/threads/:topic_id/items. Isso retorna as enquetes e conclusões da conversa junto com seus outros itens. Obtenha todas as páginas para incluir a conversa completa.

GET /api/user0/polls

Parâmetros

Compatibilidade com versões anteriores: per e from são aceitos como aliases de limit e offset e continuarão funcionando.

Exemplo

curl 'https://www.loomio.com/api/user0/polls?group_id=123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Editar enquete

Edite uma enquete como o usuário da chave de API. Aplicam-se as mesmas permissões do Loomio: o usuário deve ter permissão para editar essa enquete.

PATCH /api/user0/polls/:id

Parâmetros

Exemplo

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "title": "updated poll title",
    "details": "updated details",
    "details_format": "md"
  }'

Editar opções detalhadas

Obtenha os IDs das opções no array poll_options de uma resposta de criação ou consulta. Envie apenas os campos a alterar, junto com o id de cada opção existente:

curl https://www.loomio.com/api/user0/polls/123 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "poll_options_attributes": [
      {
        "id": 456,
        "meaning": "Updated explanation",
        "prompt": "What would improve this proposal?"
      },
      {
        "name": "Abstain",
        "meaning": "I leave the decision to others",
        "icon": "abstain",
        "priority": 2
      }
    ]
  }'

Os IDs das opções devem pertencer à enquete que está sendo editada. A edição exige permissão para editar a enquete, e enquetes encerradas não podem ser editadas. Enquetes anônimas também impedem alterações na configuração das opções após o envio do primeiro voto.

Excluir enquete logicamente

Exclua uma enquete logicamente como o usuário da chave de API. Isso descarta a enquete e mantém seu registro.

DELETE /api/user0/polls/:id

Exemplo

curl https://www.loomio.com/api/user0/polls/123 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Busca

Busque discussões, comentários, enquetes, votos e conclusões visíveis para o usuário da chave de API. Os resultados incluem conteúdo público mesmo quando o usuário não é membro do grupo correspondente; o conteúdo privado continua sujeito às regras normais de visibilidade das conversas.

GET /api/user0/search

Parâmetros

curl 'https://www.loomio.com/api/user0/search?query=quarterly+planning&type=Discussion' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A resposta contém um array search_results. Cada resultado identifica o registro correspondente e seu contexto visível com campos que incluem searchable_type, searchable_id, highlight, group_id, group_name, discussion_key, poll_key, author_id, author_name, authored_at e tags. Os campos que não se aplicam a um resultado são null.

Conversas

Listar conversas

Liste as conversas de discussão e de enquete visíveis ao usuário da chave de API, ordenadas pela atividade mais recente. O ID de uma conversa é seu topic_id.

GET /api/user0/threads

Parâmetros

Exemplo

curl 'https://www.loomio.com/api/user0/threads?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Ler conversa

Leia uma conversa, sua sequência ordenada de eventos ou seu documento Markdown completo com o conteúdo visível.

GET /api/user0/threads/:topic_id

GET /api/user0/threads/:topic_id/items

GET /api/user0/threads/:topic_id/markdown

O endpoint items aceita estes parâmetros de paginação:

Exemplo

GET https://www.loomio.com/api/user0/threads/<topic_id>
GET https://www.loomio.com/api/user0/threads/<topic_id>/items?limit=50&offset=0
GET https://www.loomio.com/api/user0/threads/<topic_id>/markdown

O endpoint items retorna uma página da sequência de eventos em ordem crescente, incluindo comentários, enquetes, votos e conclusões visíveis. meta.total é o número total de itens da conversa. Busque as páginas seguintes para ler toda a sequência. O endpoint markdown retorna todo o conteúdo visível da conversa em um único documento Markdown. Os motivos dos votos são incluídos somente quando são visíveis ao usuário da chave de API.

Todos os endpoints de conversas aplicam as mesmas permissões da interface do Loomio. A chave de API não concede acesso a uma conversa que o usuário normalmente não pode abrir.

Webhooks

A API do usuário funciona por requisições: uma integração chama o Loomio quando precisa ler ou alterar dados. Um webhook de grupo permite o envio na direção oposta. O Loomio envia os eventos selecionados do grupo ao seu endpoint assim que acontecem, para que a integração não precise consultar periodicamente a API REST em busca de alterações.

Os webhooks são configurados por grupo e exigem permissão de administrador do grupo. Eles podem ser gerenciados pela interface do Loomio:

1. Abra o grupo.
2. Abra o menu do grupo e selecione Integrações de bate-papo.
3. Adicione a integração correspondente ao formato de dados que seu endpoint aceita. Para um endpoint de uso geral, use o formato Mattermost/Markdown.
4. Insira um nome e a URL de destino.
5. Selecione os eventos que o Loomio deve enviar automaticamente.
6. Salve a integração e use Conexão de teste para enviar uma mensagem de teste.

Use um destino HTTPS com uma URL que não possa ser adivinhada. O Loomio exige que o destino seja resolvido para um endereço público e bloqueia requisições para endereços de redes locais ou privadas.

Agentes e outras integrações também podem gerenciar webhooks pelos endpoints de chatbots com autenticação Bearer descritos abaixo. O recurso se chama chatbots para manter a compatibilidade com as integrações de bate-papo do Loomio, mas também representa webhooks gerais de saída.

Listar webhooks

Retorna as integrações de bate-papo configuradas para um grupo. O usuário da chave de API deve ser administrador desse grupo. A resposta inclui URLs de destino, portanto não deve ser exposta aos membros comuns do grupo.

GET /api/user0/chatbots?group_id=123

curl 'https://www.loomio.com/api/user0/chatbots?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A resposta contém uma página de chatbots ordenada pelo ID da integração em ordem crescente, com a contagem total do grupo em meta.total. Cada integração tem estes campos:

Criar um webhook

POST /api/user0/chatbots

curl https://www.loomio.com/api/user0/chatbots \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "name": "Planning system",
    "kind": "webhook",
    "webhook_kind": "markdown",
    "server": "https://hooks.example.org/loomio/unguessable-token",
    "event_kinds": [
      "new_discussion",
      "new_comment",
      "poll_created",
      "outcome_created"
    ],
    "notification_only": false
  }'

O usuário da chave de API deve ser administrador do grupo indicado por group_id. O destino é validado como uma URL pública antes de ser salvo.

Atualizar um webhook

PATCH /api/user0/chatbots/:id

Envie os campos que devem ser alterados. O webhook não pode ser transferido para outro grupo por meio da alteração de group_id.

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "name": "Planning events",
    "event_kinds": [
      "new_discussion",
      "outcome_created"
    ]
  }'

Testar um destino de webhook

Envie uma mensagem de teste compatível com Markdown para um destino antes ou depois de salvar sua configuração.

POST /api/user0/chatbots/check

curl https://www.loomio.com/api/user0/chatbots/check \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  --json '{
    "group_id": 123,
    "server": "https://hooks.example.org/loomio/unguessable-token"
  }'

Excluir um webhook

DELETE /api/user0/chatbots/:id

curl https://www.loomio.com/api/user0/chatbots/456 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_API_KEY'

Excluir a configuração interrompe as entregas futuras. Isso não exclui nenhum conteúdo do grupo no Loomio.

Tipos de evento

Um webhook pode se inscrever nestes tipos de evento:

O webhook pertence a um grupo e recebe os eventos desse grupo nos quais está inscrito. As pessoas também podem selecionar explicitamente a integração ao compartilhar conteúdo ou enviar algumas notificações, mesmo quando o evento automático correspondente não está selecionado.

Entrega HTTP

O Loomio envia um POST HTTP assíncrono para a URL configurada com este cabeçalho:

Content-Type: application/json; charset=utf-8

O tempo limite da requisição é de cinco segundos. Uma resposta 2xx, incluindo 204 No Content, é considerada bem-sucedida. Os serviços que recebem webhooks devem responder rapidamente, processar tarefas mais demoradas de forma assíncrona e tolerar entregas duplicadas ou fora de ordem.

Atualmente, o Loomio não adiciona uma assinatura de webhook, um cabeçalho com segredo compartilhado, um ID de evento ou um ID de entrega. Trate a URL de destino completa como uma credencial, não a exponha publicamente e inclua na URL um token que não possa ser adivinhado quando o serviço receptor permitir. Se você precisar de um esquema de eventos estável e legível por máquina ou de entregas assinadas, use o webhook como uma notificação de alteração e obtenha os registros atuais pela API do usuário autenticada.

Formatos de payload

Os payloads de webhook são mensagens formatadas para exibição em serviços de bate-papo. Eles não são registros completos e serializados do Loomio. Os links na mensagem identificam o conteúdo afetado no Loomio; uma integração pode consultar a API do usuário quando precisar do estado atual em formato estruturado.

Por exemplo, o formato Markdown geral envia um corpo com esta estrutura:

{
  "text": "Ada started a discussion: [Quarterly planning](https://example.loomio.org/d/example)",
  "icon_url": "https://example.loomio.org/path/to/group-logo.png",
  "username": "Loomio"
}

O texto exato da mensagem depende do evento, do idioma do grupo, da configuração para enviar apenas a notificação e da versão do Loomio. Os serviços receptores devem usar os campos de nível superior documentados para o formato selecionado, em vez de analisar a redação das frases.