Estrutura do Payload
O que é
Payload é o "pacote de dados" enviado ou recebido em um webhook. Entender sua estrutura é essencial para integrar corretamente seus sistemas.
Estrutura Geral
Todo payload do Deskito segue este formato:
json
{
"event": "nome.do.evento",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
// Dados específicos do evento
}
}| Campo | Tipo | Descrição |
|---|---|---|
event | string | Identificador do evento |
timestamp | ISO 8601 | Data/hora do evento |
data | object | Dados do registro afetado |
Payloads de Entrada (Receber Leads)
Campos aceitos
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | ✅ | Nome do lead |
email | string | ❌ | Email do lead |
phone | string | ❌ | Telefone |
company | string | ❌ | Nome da empresa |
source | string | ❌ | Origem do lead |
notes | string | ❌ | Observações |
estimated_value | number | ❌ | Valor estimado |
tags | array | ❌ | Lista de tags |
custom_fields | object | ❌ | Campos personalizados |
Exemplo mínimo
json
{
"name": "João Silva"
}Exemplo completo
json
{
"name": "João Silva",
"email": "joao@empresa.com",
"phone": "(11) 99999-9999",
"company": "Tech Solutions Ltda",
"source": "landing-page-servicos",
"notes": "Interessado em desenvolvimento de site",
"estimated_value": 5000,
"tags": ["site", "urgente"],
"custom_fields": {
"segmento": "tecnologia",
"funcionarios": "10-50"
}
}Payloads de Saída (Eventos)
Lead / Cliente
json
{
"event": "lead.created",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
"id": "uuid-do-lead",
"name": "João Silva",
"email": "joao@empresa.com",
"phone": "(11) 99999-9999",
"company": "Tech Solutions",
"status": "novo_lead",
"source": "landing-page",
"estimated_value": 5000,
"created_at": "2026-02-02T14:30:00.000Z",
"updated_at": "2026-02-02T14:30:00.000Z"
}
}Negócio / Deal
json
{
"event": "deal.won",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
"id": "uuid-do-negocio",
"title": "Projeto Website",
"status": "ganho",
"proposal_value": 15000,
"expected_revenue": 15000,
"probability": 100,
"closing_date": "2026-02-02",
"client": {
"id": "uuid-do-cliente",
"name": "Tech Solutions",
"email": "contato@tech.com"
},
"owner": {
"id": "uuid-do-vendedor",
"name": "Maria Vendedora"
},
"created_at": "2026-01-15T10:00:00.000Z",
"updated_at": "2026-02-02T14:30:00.000Z"
}
}Fatura / Invoice
json
{
"event": "invoice.paid",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
"id": "uuid-da-fatura",
"invoice_number": "FAT-2026-0042",
"amount": 5000,
"status": "paid",
"due_date": "2026-02-05",
"paid_at": "2026-02-02T14:30:00.000Z",
"payment_method": "pix",
"client": {
"id": "uuid-do-cliente",
"name": "Tech Solutions",
"email": "financeiro@tech.com"
},
"items": [
{
"description": "Desenvolvimento de Website",
"quantity": 1,
"unit_price": 5000,
"total": 5000
}
]
}
}Projeto
json
{
"event": "project.completed",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
"id": "uuid-do-projeto",
"name": "Website Tech Solutions",
"status": "concluido",
"progress": 100,
"start_date": "2026-01-01",
"end_date": "2026-02-02",
"client": {
"id": "uuid-do-cliente",
"name": "Tech Solutions"
},
"tasks_total": 25,
"tasks_completed": 25,
"created_at": "2026-01-01T08:00:00.000Z",
"updated_at": "2026-02-02T14:30:00.000Z"
}
}Tarefa
json
{
"event": "task.completed",
"timestamp": "2026-02-02T14:30:00.000Z",
"data": {
"id": "uuid-da-tarefa",
"title": "Criar wireframes",
"description": "Wireframes das páginas principais",
"status": "concluida",
"priority": "high",
"due_date": "2026-02-01",
"completed_at": "2026-02-02T14:30:00.000Z",
"project": {
"id": "uuid-do-projeto",
"name": "Website Tech Solutions"
},
"assignee": {
"id": "uuid-do-responsavel",
"name": "Designer João"
}
}
}Tipos de Dados
| Tipo | Formato | Exemplo |
|---|---|---|
| string | Texto | "João Silva" |
| number | Numérico | 5000 ou 99.90 |
| boolean | Verdadeiro/Falso | true ou false |
| array | Lista | ["tag1", "tag2"] |
| object | Objeto | {"key": "value"} |
| date | ISO 8601 | "2026-02-02" |
| datetime | ISO 8601 | "2026-02-02T14:30:00.000Z" |
| uuid | UUID v4 | "550e8400-e29b-41d4-a716-446655440000" |
Dicas e boas práticas
- Sempre valide o formato antes de processar
- Trate campos opcionais como possivelmente nulos
- Use o timestamp para ordenação de eventos
- Armazene o ID para referência futura
- Implemente retry para falhas de processamento
Links relacionados: