> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegly.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de Webhooks

> Eventos que a API da Wegly pode disparar para webhooks configurados, com payloads e tipos enviados em cada disparo.

Esta página documenta os eventos de webhook de saída que a Wegly pode enviar para integrações externas.

Cada evento é entregue como uma requisição `POST` para a URL configurada na assinatura de webhook ativa. O endpoint de destino deve responder qualquer status HTTP `2xx` para confirmar o recebimento. Respostas fora de `2xx` são registradas como falha e podem ser reenviadas conforme o número de tentativas configurado na assinatura.

## Formato da entrega

### Headers enviados

| Header              | Tipo                 | Descrição                                                                   |
| ------------------- | -------------------- | --------------------------------------------------------------------------- |
| `content-type`      | `application/json`   | Tipo do corpo enviado.                                                      |
| `user-agent`        | `wegly-webhooks/1.0` | Identificação do emissor dos webhooks da Wegly.                             |
| `x-wegly-event`     | `WebhookEventKey`    | Chave técnica do evento disparado.                                          |
| `x-wegly-signature` | `string`             | Assinatura HMAC SHA-256 do corpo JSON, gerada com o `secret` da assinatura. |

### Envelope padrão

Todos os eventos usam o mesmo envelope:

```ts theme={null}
type ISODateString = string;
type UUID = string;

interface WeglyWebhookEnvelope<
  TEvent extends WebhookEventKey,
  TPayload,
> {
  event_key: TEvent;
  payload: TPayload;
}
```

Exemplo:

```json theme={null}
{
  "event_key": "lead.created",
  "payload": {
    "lead": {
      "id": "11111111-1111-4111-8111-111111111111",
      "code": 1024,
      "title": "Lead - Evento corporativo",
      "status": 1,
      "created_at": "2026-06-02T12:00:00.000Z",
      "updated_at": "2026-06-02T12:05:00.000Z"
    }
  }
}
```

<Note>
  Algumas ações podem disparar mais de um evento. Por exemplo: ao mover um lead de etapa, a Wegly pode enviar `lead.stage_changed` e também `lead.updated`, caso existam assinaturas ativas para ambos.
</Note>

## Eventos disponíveis

```ts theme={null}
type WebhookEventKey =
  | 'lead.created'
  | 'lead.updated'
  | 'lead.stage_changed'
  | 'lead.won'
  | 'lead.lost'
  | 'lead.tag_added'
  | 'lead.tag_removed'
  | 'lead.custom_field_updated'
  | 'lead.custom_field_removed'
  | 'lead.quality_updated'
  | 'deal.created'
  | 'deal.updated'
  | 'deal.stage_changed'
  | 'deal.won'
  | 'deal.lost'
  | 'deal.tag_added'
  | 'deal.tag_removed'
  | 'deal.custom_field_updated'
  | 'deal.custom_field_removed'
  | 'deal.quality_updated'
  | 'chat.message_sent'
  | 'chat.message_received'
  | 'delivery.created'
  | 'delivery.updated'
  | 'delivery.stage_changed'
  | 'delivery.completed'
  | 'task.completed'
  | 'contract.created'
  | 'contract.updated'
  | 'contract.canceled'
  | 'contract.renewed'
  | 'contract.completed'
  | 'satisfaction.public_submission_created';
```

## Leads

| Evento                      | Quando dispara                                                         | Payload enviado                 |
| --------------------------- | ---------------------------------------------------------------------- | ------------------------------- |
| `lead.created`              | Quando um lead é criado pela API interna ou por integração externa.    | `LeadCreatedPayload`            |
| `lead.updated`              | Quando dados do lead são alterados.                                    | `LeadSnapshot`                  |
| `lead.stage_changed`        | Quando um lead é movido para outra etapa do funil.                     | `LeadStageChangedPayload`       |
| `lead.won`                  | Quando um lead é marcado como ganho.                                   | `LeadWonPayload`                |
| `lead.lost`                 | Quando um lead é marcado como perdido.                                 | `LeadLostPayload`               |
| `lead.tag_added`            | Quando uma ou mais tags são adicionadas ao lead.                       | `LeadTagAddedPayload`           |
| `lead.tag_removed`          | Quando uma tag é removida do lead.                                     | `LeadTagRemovedPayload`         |
| `lead.custom_field_updated` | Quando um valor de campo personalizado do lead é criado ou atualizado. | `LeadCustomFieldUpdatedPayload` |
| `lead.custom_field_removed` | Quando um valor de campo personalizado do lead é removido.             | `LeadCustomFieldRemovedPayload` |
| `lead.quality_updated`      | Quando a qualificação do lead é criada ou alterada.                    | `LeadQualityUpdatedPayload`     |

```ts theme={null}
interface LeadSnapshot {
  id: UUID;
  code: number;
  title: string;
  status: number; // 1=Aberto, 2=Ganho, 3=Perdido.
  value?: number | null;
  visibility?: number;
  negotiation_mode?: string | null;
  quality_rating?: number | null;
  quality_reason?: string | null;
  created_at: ISODateString;
  updated_at: ISODateString;
  archived_at?: ISODateString | null;
  won_date?: ISODateString | null;
  lost_date?: ISODateString | null;
  lost_reason_description?: string | null;
  responsible?: UserSummary | null;
  created_by?: UserSummary | null;
  stage?: Record<string, unknown> | null;
  lead_source?: Record<string, unknown> | null;
  marketing_lead_source?: Record<string, unknown> | null;
  participants?: Array<Record<string, unknown>>;
  organization?: Record<string, unknown> | null;
  custom_fields?: Array<Record<string, unknown>>;
  tags?: TagSummary[];
  proposals?: Array<Record<string, unknown>>;
  followers?: UserSummary[];
  has_whatsapp_chat?: boolean;
  whatsapp_chats?: WhatsappChatSummary[];
  [key: string]: unknown;
}

interface LeadCreatedPayload {
  lead: LeadSnapshot;
  custom_fields_changed?: CustomFieldChange[];
  previous_quality?: number | null;
  previous_quality_reason?: string | null;
  new_quality?: number | null;
  new_quality_reason?: string | null;
}

interface LeadStageChangedPayload {
  previous_stage: StageSummary | null;
  current_stage: StageSummary | null;
  lead: LeadSnapshot;
}

interface LeadWonPayload {
  lead: LeadSnapshot;
  won_date: ISODateString;
  won_by: ActorSummary;
  deal: Record<string, unknown> | null;
}

interface LeadLostPayload {
  lead: LeadSnapshot;
  lost_date: ISODateString;
  lost_by: ActorSummary;
  loss_reason: LossReasonSummary | null;
  loss_reason_description: string | null;
}

interface LeadTagAddedPayload {
  lead: LeadSnapshot;
  added_tags: TagSummary[];
}

interface LeadTagRemovedPayload {
  lead: LeadSnapshot;
  removed_tags: TagSummary[];
}

interface LeadCustomFieldUpdatedPayload {
  lead: LeadSnapshot;
  custom_fields_changed: CustomFieldChange[];
}

interface LeadCustomFieldRemovedPayload {
  lead: LeadSnapshot;
  removed_fields: RemovedCustomField[];
}

interface LeadQualityUpdatedPayload {
  lead: LeadSnapshot;
  previous_quality: number | null;
  previous_quality_reason: string | null;
  new_quality: number;
  new_quality_reason: string | null;
}
```

## Oportunidades

| Evento                      | Quando dispara                                                                 | Payload enviado                 |
| --------------------------- | ------------------------------------------------------------------------------ | ------------------------------- |
| `deal.created`              | Quando uma oportunidade é criada.                                              | `DealCreatedPayload`            |
| `deal.updated`              | Quando dados da oportunidade são alterados.                                    | `DealSnapshot`                  |
| `deal.stage_changed`        | Quando uma oportunidade é movida para outra etapa do funil.                    | `DealStageChangedPayload`       |
| `deal.won`                  | Quando uma oportunidade é marcada como ganha.                                  | `DealWonPayload`                |
| `deal.lost`                 | Quando uma oportunidade é marcada como perdida.                                | `DealLostPayload`               |
| `deal.tag_added`            | Quando uma ou mais tags são adicionadas à oportunidade.                        | `DealTagAddedPayload`           |
| `deal.tag_removed`          | Quando uma tag é removida da oportunidade.                                     | `DealTagRemovedPayload`         |
| `deal.custom_field_updated` | Quando um valor de campo personalizado da oportunidade é criado ou atualizado. | `DealCustomFieldUpdatedPayload` |
| `deal.custom_field_removed` | Quando um valor de campo personalizado da oportunidade é removido.             | `DealCustomFieldRemovedPayload` |
| `deal.quality_updated`      | Quando a qualificação da oportunidade é criada ou alterada.                    | `DealQualityUpdatedPayload`     |

```ts theme={null}
interface DealSnapshot {
  id: UUID;
  code: number;
  title: string;
  status: number; // 1=Aberta, 2=Ganha, 3=Perdida.
  value?: number | null;
  visibility?: number;
  negotiation_mode?: string | null;
  quality_rating?: number | null;
  quality_reason?: string | null;
  created_at: ISODateString;
  updated_at: ISODateString;
  archived_at?: ISODateString | null;
  won_date?: ISODateString | null;
  lost_date?: ISODateString | null;
  lost_reason_description?: string | null;
  responsible?: UserSummary | null;
  created_by?: UserSummary | null;
  stage?: Record<string, unknown> | null;
  lead_source?: Record<string, unknown> | null;
  marketing_lead_source?: Record<string, unknown> | null;
  participants?: Array<Record<string, unknown>>;
  organization?: Record<string, unknown> | null;
  custom_fields?: Array<Record<string, unknown>>;
  tags?: TagSummary[];
  proposals?: Array<Record<string, unknown>>;
  followers?: UserSummary[];
  has_whatsapp_chat?: boolean;
  whatsapp_chats?: WhatsappChatSummary[];
  [key: string]: unknown;
}

interface DealCreatedPayload {
  deal: DealSnapshot;
  custom_fields_changed?: CustomFieldChange[];
}

interface DealStageChangedPayload {
  previous_stage: StageSummary | null;
  current_stage: StageSummary | null;
  deal: DealSnapshot;
}

interface DealWonPayload {
  deal: DealSnapshot;
  won_date: ISODateString;
  won_by: ActorSummary;
  customer_id: UUID | null;
}

interface DealLostPayload {
  deal: DealSnapshot;
  lost_date: ISODateString;
  lost_by: ActorSummary;
  loss_reason: LossReasonSummary | null;
  loss_reason_description: string | null;
}

interface DealTagAddedPayload {
  deal: DealSnapshot;
  added_tags: TagSummary[];
}

interface DealTagRemovedPayload {
  deal: DealSnapshot;
  removed_tags: TagSummary[];
}

interface DealCustomFieldUpdatedPayload {
  deal: DealSnapshot;
  custom_fields_changed: CustomFieldChange[];
}

interface DealCustomFieldRemovedPayload {
  deal: DealSnapshot;
  removed_fields: RemovedCustomField[];
}

interface DealQualityUpdatedPayload {
  deal: DealSnapshot;
  previous_quality: number | null;
  previous_quality_reason: string | null;
  new_quality: number;
  new_quality_reason: string | null;
}
```

## Chats

| Evento                  | Quando dispara                                        | Payload enviado      |
| ----------------------- | ----------------------------------------------------- | -------------------- |
| `chat.message_sent`     | Quando uma mensagem é enviada pela Wegly no chat.     | `ChatMessagePayload` |
| `chat.message_received` | Quando uma mensagem é recebida de um contato no chat. | `ChatMessagePayload` |

```ts theme={null}
interface ChatMessagePayload {
  id: UUID;
  type: string;
  origin: string;
  from_me: boolean;
  sent_via: 'CONTACT' | 'API' | 'MOBILE_DEVICE' | 'SYSTEM';
  status: string;
  body_text: string | null;
  content_payload: Record<string, unknown> | null;
  reactions: Array<Record<string, unknown>>;
  meta_timestamp: ISODateString;
  created_at: ISODateString;
  is_history: boolean;
  history_phase?: number | null;
  history_chunk_order?: number | null;
  history_progress?: number | null;
  is_media_placeholder: boolean;
  is_forwarded: boolean;
  agent?: Record<string, unknown> | null;
  user?: Record<string, unknown> | null;
  media?: Record<string, unknown> | null;
  call?: Record<string, unknown> | null;
  quoted_message?: Record<string, unknown> | null;
  associated_leads: AssociatedCrmRecord[];
  associated_deals: AssociatedCrmRecord[];
  [key: string]: unknown;
}

interface AssociatedCrmRecord {
  id: UUID;
  title: string;
  status: number;
}
```

## Entregas

| Evento                   | Quando dispara                                         | Payload enviado               |
| ------------------------ | ------------------------------------------------------ | ----------------------------- |
| `delivery.created`       | Quando uma entrega é criada.                           | `DeliveryCreatedPayload`      |
| `delivery.updated`       | Quando dados da entrega são alterados.                 | `DeliverySnapshot`            |
| `delivery.stage_changed` | Quando uma entrega é movida para outra etapa do fluxo. | `DeliveryStageChangedPayload` |
| `delivery.completed`     | Quando uma entrega é concluída.                        | `DeliveryCompletedPayload`    |

```ts theme={null}
interface DeliverySnapshot {
  id: UUID;
  code: number;
  title: string;
  description: string | null;
  status: number;
  planned_start_date: ISODateString | null;
  planned_end_date: ISODateString | null;
  started_at: ISODateString | null;
  delivered_at: ISODateString | null;
  cancelled_at: ISODateString | null;
  cancellation_reason: string | null;
  created_at: ISODateString;
  updated_at: ISODateString;
  company_id: UUID;
  pipeline_id: UUID;
  stage_id: UUID;
  customer_id: UUID;
  deal_id: UUID | null;
  responsible_id: UUID | null;
  created_by: UUID | null;
  pipeline?: Record<string, unknown>;
  stage?: Record<string, unknown>;
  customer?: Record<string, unknown>;
  deal?: Record<string, unknown> | null;
  responsible?: UserSummary | null;
  created_by_user?: UserSummary | null;
  crm_delivery_participant?: Array<Record<string, unknown>>;
  crm_delivery_stage_deadline?: Array<Record<string, unknown>>;
  custom_fields?: Array<Record<string, unknown>>;
  pending_delivery_indicators?: Array<Record<string, unknown>>;
  has_pending_delivery_indicators?: boolean;
  has_overdue_delivery_indicators?: boolean;
  stage_durations?: Array<Record<string, unknown>>;
  crm_delivery_stage_assignment?: Array<Record<string, unknown>>;
  crm_delivery_deadline_change?: Array<Record<string, unknown>>;
  [key: string]: unknown;
}

interface DeliveryCreatedPayload {
  delivery: DeliverySnapshot;
}

interface DeliveryStageChangedPayload {
  previous_stage: StageSummary | null;
  current_stage: StageSummary | null;
  delivery: DeliverySnapshot;
}

interface DeliveryCompletedPayload {
  delivery: DeliverySnapshot;
  completed_at: ISODateString | null;
}
```

## Tarefas

| Evento           | Quando dispara                                      | Payload enviado        |
| ---------------- | --------------------------------------------------- | ---------------------- |
| `task.completed` | Quando uma tarefa passa de pendente para concluída. | `TaskCompletedPayload` |

```ts theme={null}
interface TaskCompletedPayload {
  task: TaskSnapshot;
  completed_at: ISODateString | null;
}

interface TaskSnapshot {
  id: UUID;
  title: string;
  description: string | null;
  is_personal: boolean;
  priority: number;
  start_date: ISODateString | null;
  end_date: ISODateString | null;
  has_time: boolean;
  completed_at: ISODateString;
  meeting_outcome: number | null;
  meeting_outcome_notes: string | null;
  created_at: ISODateString;
  updated_at: ISODateString;
  crm_task_type_id: UUID;
  crm_task_stage_id: UUID;
  crm_lead_id: UUID | null;
  crm_deal_id: UUID | null;
  crm_delivery_id: UUID | null;
  crm_person_id: UUID | null;
  crm_organization_id: UUID | null;
  responsible_id: UUID | null;
  created_by: UserSummary | null;
  completed_by: UserSummary | null;
  responsible: UserSummary | null;
  crm_task_type: Record<string, unknown>;
  crm_task_stage: Record<string, unknown>;
  crm_lead: Record<string, unknown> | null;
  crm_deal: Record<string, unknown> | null;
  crm_delivery: Record<string, unknown> | null;
  crm_person: Record<string, unknown> | null;
  crm_organization: Record<string, unknown> | null;
  mentions: Array<Record<string, unknown>>;
  reminders_minutes: number[];
  is_recurring: boolean;
  recurrence: Record<string, unknown> | null;
  meeting_provider: string | null;
  provider: string | null;
  recordings: Array<Record<string, unknown>>;
  comments?: Array<Record<string, unknown>>;
  [key: string]: unknown;
}
```

## Contratos

| Evento               | Quando dispara                                         | Payload enviado            |
| -------------------- | ------------------------------------------------------ | -------------------------- |
| `contract.created`   | Quando um contrato é criado.                           | `ContractCreatedPayload`   |
| `contract.updated`   | Quando dados do contrato são alterados.                | `ContractSnapshot`         |
| `contract.canceled`  | Quando um contrato é cancelado.                        | `ContractCanceledPayload`  |
| `contract.renewed`   | Quando um contrato é renovado e gera um novo contrato. | `ContractRenewedPayload`   |
| `contract.completed` | Quando um contrato é concluído.                        | `ContractCompletedPayload` |

```ts theme={null}
interface ContractSnapshot {
  id: UUID;
  code: number;
  status: number; // 1=Ativo, 2=Cancelado, 3=Concluído.
  title: string;
  description: string | null;
  start_date: ISODateString;
  end_date: ISODateString | null;
  renewal_automatic: boolean;
  renewal_notice_days: number | null;
  cancelled_at: ISODateString | null;
  cancellation_reason: string | null;
  cancellation_details: string | null;
  loss_reason: Record<string, unknown> | null;
  completed_at: ISODateString | null;
  created_at: ISODateString;
  updated_at: ISODateString;
  customer: Record<string, unknown>;
  deal: Record<string, unknown> | null;
  deals: Array<Record<string, unknown>>;
  deal_links: Array<Record<string, unknown>>;
  responsible: UserSummary | null;
  created_by: UserSummary | null;
  totals: Record<string, unknown>;
  items: Array<Record<string, unknown>>;
  partners?: Array<Record<string, unknown>>;
  [key: string]: unknown;
}

interface ContractCreatedPayload {
  contract: ContractSnapshot;
}

interface ContractCanceledPayload {
  contract: ContractSnapshot;
  canceled_at: ISODateString | null;
  cancellation_reason: string | null;
}

interface ContractRenewedPayload {
  contract: ContractSnapshot;
  renewed_from_contract: {
    id: UUID;
    code: number;
  };
}

interface ContractCompletedPayload {
  contract: ContractSnapshot;
  completed_at: ISODateString | null;
}
```

## Satisfação

| Evento                                   | Quando dispara                                                    | Payload enviado                              |
| ---------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------- |
| `satisfaction.public_submission_created` | Quando um formulário de satisfação é respondido por link público. | `SatisfactionPublicSubmissionCreatedPayload` |

```ts theme={null}
interface SatisfactionPublicSubmissionCreatedPayload {
  submission: SatisfactionSubmissionSnapshot;
  link: {
    id: UUID;
    token: string;
    form_id: UUID;
    created_by: UUID | null;
    crm_person_id: UUID;
    crm_deal_id: UUID | null;
    crm_delivery_id: UUID | null;
  };
}

interface SatisfactionSubmissionSnapshot {
  id: UUID;
  form_id: UUID;
  company_id: UUID;
  crm_person_id: UUID;
  crm_deal_id: UUID | null;
  crm_delivery_id: UUID | null;
  submitted_by: UUID | null;
  average_score: number | null;
  created_at: ISODateString;
  responses: Array<Record<string, unknown>>;
  person: Record<string, unknown> | null;
  deal: Record<string, unknown> | null;
  delivery: Record<string, unknown> | null;
  user: UserSummary | null;
  post_submit?: Record<string, unknown> | null;
  [key: string]: unknown;
}
```

## Tipos compartilhados

```ts theme={null}
interface UserSummary {
  id: UUID;
  name: string | null;
  avatar?: string | null;
}

interface ActorSummary {
  id: UUID;
  name: string | null;
}

interface StageSummary {
  id: UUID;
  name: string | null;
  pipeline: {
    id: UUID;
    name: string | null;
  } | null;
}

interface TagSummary {
  id: UUID;
  name: string | null;
  color?: string | null;
}

interface CustomFieldChange {
  custom_field_id?: UUID | null;
  value?: string | null;
  option_id?: UUID | null;
  option_ids?: UUID[];
  field_name?: string | null;
  field_type?: number | null;
  [key: string]: unknown;
}

interface RemovedCustomField {
  id: UUID;
  name: string | null;
  type: number | null;
}

interface LossReasonSummary {
  id: UUID;
  name: string;
}

interface WhatsappChatSummary {
  id: UUID;
  status?: number | null;
  display_number?: string | null;
  raw_number?: string | null;
  person?: Record<string, unknown> | null;
  responsible_agent?: Record<string, unknown> | null;
  participants?: Array<Record<string, unknown>>;
  [key: string]: unknown;
}
```