# Tickets: webhook e Linear

Leve os tickets ao seu sistema com o webhook próprio ou conecte-os ao Linear.

Guia Todos os planos Sem chave de API

## Onde configurar

No ByDomu, Configurações › Canais e integrações › Tickets: Linear e webhook. Funciona em todos os planos e não pede chave de API: alguém da equipe configura no painel. É um webhook normal (mesma assinatura, mesma fila com novas tentativas, mesmo registro de entregas) assinado só a ticket.*.

## Conecte seu sistema com o webhook

- Cole o endereço (https://…) do seu servidor, do Jira ou Zendesk por meio da sua própria ponte, ou do Zapier, Make ou n8n.
- Escolha os eventos. Por padrão vão ticket.created, ticket.status_changed e ticket.resolved; ticket.updated e ticket.note_added são marcados à parte.
- Copie o segredo e guarde no seu sistema para verificar X-Domu-Signature. Você pode vê-lo de novo ou rotacioná-lo; ao rotacionar, o anterior para de servir na hora.
- «Enviar um teste» manda uma entrega com X-Webhook-Test: true e data.message; embaixo você vê as últimas entregas com o código de resposta.

Quando sai Evento

Foi criado um ticket. Traz o ticket (com o link para o painel) e o contato, se houver. `ticket.created`

Mudou o título, o resumo, a prioridade, o responsável ou as etiquetas. changedFields diz quais. `ticket.updated`

O ticket mudou de status (PENDING, IN_PROGRESS ou RESOLVED). previousStatus traz o anterior. `ticket.status_changed`

Foi adicionada uma nota interna ao ticket, no ByDomu ou como comentário no Linear (note.source). `ticket.note_added`

O ticket foi resolvido. Sai junto com ticket.status_changed. `ticket.resolved`

## O que chega em cada entrega

data.ticket traz o número e o código (T-0012), status, prioridade, canal, etiquetas, responsável, o issue do Linear se existir e url, o link para o ticket no painel; data.contact, o contato se houver. Uma mudança para RESOLVED manda ticket.status_changed e ticket.resolved: descarte repetidos pelo id.

**Entrega · exemplo**

ticket.created:

```
{
  "event": "ticket.created",
  "id": "5f3a0c1e-7d2b-4f7e-9a51-0b6c1d2e3f40",
  "type": "ticket.created",
  "timestamp": "2026-09-22T14:30:00.000Z",
  "organizationId": "clx1org001",
  "actor": {
    "kind": "USER",
    "userId": "clx1usr001"
  },
  "data": {
    "ticket": {
      "id": "clx1tkt001",
      "number": 12,
      "code": "T-0012",
      "title": "No llegan las fotos al portal",
      "summary": "La clienta dice que la ficha P-0042 se ve sin fotos desde ayer.",
      "status": "PENDING",
      "priority": "HIGH",
      "channel": "WHATSAPP",
      "labels": [
        "Portales"
      ],
      "assignedToId": "clx1usr001",
      "assignedToName": "Andrés Mejía",
      "contactId": "clx1con001",
      "conversationId": "clx1cnv001",
      "linearIssueKey": null,
      "url": "https://www.bydomu.com/inbox/tickets/clx1tkt001",
      "resolvedAt": null,
      "createdAt": "2026-09-22T14:30:00.000Z",
      "updatedAt": "2026-09-22T14:30:00.000Z"
    },
    "contact": {
      "id": "clx1con001",
      "code": "C-0042",
      "firstName": "Laura",
      "lastName": "Restrepo",
      "fullName": "Laura Restrepo",
      "email": "laura.restrepo@example.com",
      "phone": "+573000000001",
      "source": "WEBSITE",
      "status": "QUALIFIED",
      "type": "CLIENT",
      "score": 72,
      "ownerId": "clx1usr001",
      "preferredCity": "Bogotá",
      "preferredType": "APARTMENT",
      "budget": 450000000,
      "currency": "COP",
      "tags": [
        "Compra",
        "Chapinero"
      ],
      "createdAt": "2026-09-20T15:04:00.000Z"
    }
  }
}
```

ticket.status_changed:

```
{
  "event": "ticket.status_changed",
  "id": "5f3a0c1e-7d2b-4f7e-9a51-0b6c1d2e3f40",
  "type": "ticket.status_changed",
  "timestamp": "2026-09-22T14:30:00.000Z",
  "organizationId": "clx1org001",
  "actor": {
    "kind": "USER",
    "userId": "clx1usr001"
  },
  "data": {
    "ticket": {
      "id": "clx1tkt001",
      "number": 12,
      "code": "T-0012",
      "title": "No llegan las fotos al portal",
      "summary": "La clienta dice que la ficha P-0042 se ve sin fotos desde ayer.",
      "status": "IN_PROGRESS",
      "priority": "HIGH",
      "channel": "WHATSAPP",
      "labels": [
        "Portales"
      ],
      "assignedToId": "clx1usr001",
      "assignedToName": "Andrés Mejía",
      "contactId": "clx1con001",
      "conversationId": "clx1cnv001",
      "linearIssueKey": null,
      "url": "https://www.bydomu.com/inbox/tickets/clx1tkt001",
      "resolvedAt": null,
      "createdAt": "2026-09-22T14:30:00.000Z",
      "updatedAt": "2026-09-22T15:00:00.000Z"
    },
    "contact": {
      "id": "clx1con001",
      "code": "C-0042",
      "firstName": "Laura",
      "lastName": "Restrepo",
      "fullName": "Laura Restrepo",
      "email": "laura.restrepo@example.com",
      "phone": "+573000000001",
      "source": "WEBSITE",
      "status": "QUALIFIED",
      "type": "CLIENT",
      "score": 72,
      "ownerId": "clx1usr001",
      "preferredCity": "Bogotá",
      "preferredType": "APARTMENT",
      "budget": 450000000,
      "currency": "COP",
      "tags": [
        "Compra",
        "Chapinero"
      ],
      "createdAt": "2026-09-20T15:04:00.000Z"
    },
    "previousStatus": "PENDING"
  }
}
```

ticket.note_added:

```
{
  "event": "ticket.note_added",
  "id": "5f3a0c1e-7d2b-4f7e-9a51-0b6c1d2e3f40",
  "type": "ticket.note_added",
  "timestamp": "2026-09-22T14:30:00.000Z",
  "organizationId": "clx1org001",
  "actor": {
    "kind": "USER",
    "userId": "clx1usr001"
  },
  "data": {
    "ticket": {
      "id": "clx1tkt001",
      "number": 12,
      "code": "T-0012",
      "title": "No llegan las fotos al portal",
      "summary": "La clienta dice que la ficha P-0042 se ve sin fotos desde ayer.",
      "status": "PENDING",
      "priority": "HIGH",
      "channel": "WHATSAPP",
      "labels": [
        "Portales"
      ],
      "assignedToId": "clx1usr001",
      "assignedToName": "Andrés Mejía",
      "contactId": "clx1con001",
      "conversationId": "clx1cnv001",
      "linearIssueKey": "SOP-128",
      "url": "https://www.bydomu.com/inbox/tickets/clx1tkt001",
      "resolvedAt": null,
      "createdAt": "2026-09-22T14:30:00.000Z",
      "updatedAt": "2026-09-22T15:10:00.000Z"
    },
    "contact": {
      "id": "clx1con001",
      "code": "C-0042",
      "firstName": "Laura",
      "lastName": "Restrepo",
      "fullName": "Laura Restrepo",
      "email": "laura.restrepo@example.com",
      "phone": "+573000000001",
      "source": "WEBSITE",
      "status": "QUALIFIED",
      "type": "CLIENT",
      "score": 72,
      "ownerId": "clx1usr001",
      "preferredCity": "Bogotá",
      "preferredType": "APARTMENT",
      "budget": 450000000,
      "currency": "COP",
      "tags": [
        "Compra",
        "Chapinero"
      ],
      "createdAt": "2026-09-20T15:04:00.000Z"
    },
    "note": {
      "body": "Ya reprocesamos las fotos; pedirle que recargue la página.",
      "author": "Andrés Mejía",
      "source": "bydomu"
    }
  }
}
```

Com uma chave secreta e webhooks:write você também pode assinar ticket.* (e ticket.suggested, quando a Noa propõe abrir um ticket) pela API, como qualquer outro evento.

## Conecte o Linear

Na mesma tela, Conectar com Linear abre a autorização do Linear para a imobiliária toda. Depois você escolhe a equipe, quando o issue é criado e como status e prioridades se correspondem. Issues e comentários saem em nome do app, com o nome de quem escreveu no ByDomu; se ativar, levam a etiqueta «Desde ByDomu».

O quê Direção

Criar o issue (Só se eu marcar · Sempre · Nunca) `ByDomu → Linear`

Status, prioridade, responsável, etiquetas e notas `ByDomu → Linear`

Mudanças de status e prioridade, comentários novos `Linear → ByDomu`

O que muda no Linear volta como eventos: ticket.status_changed, ticket.updated (changedFields: priority) e ticket.note_added com note.source = "linear". O cliente nunca vê o Linear: só o status da solicitação.

## Se algo falhar

- **401** Seu sistema recusa a assinatura: confira o segredo atual (você o rotacionou?) e o corpo cru.
- **5xx** Há nova tentativa e aparece nas entregas recentes: Até 5 tentativas (0 s, 5 s, 30 s, 2 min e 10 min) em erro de rede, 429 ou 5xx. Responda 2xx em menos de 10 s.
- **LIN** As mudanças feitas no Linear não chegam: a tela avisa se falta o webhook do app do Linear. O que é feito no ByDomu chega ao Linear.