Eventos de Webhooks

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:

type ISODateString = string;
type UUID = string;

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

Exemplo:

{
  "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"
    }
  }
}

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.

Eventos disponíveis

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`

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`

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`

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`

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`

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`

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`

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

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;
}

Integrações