{"openapi":"3.1.0","info":{"title":"Muda Webhooks API","version":"2026-07-01","description":"Receba leads e eventos no Muda usando um endpoint vinculado a uma conexao."},"servers":[{"url":"https://web.muda.chat"}],"externalDocs":{"description":"Muda Developers","url":"https://web.muda.chat/developers/webhooks/receber"},"paths":{"/api/v1/webhooks/inbound/{endpointKey}":{"post":{"operationId":"receiveMudaWebhookEvent","summary":"Enviar eventos para o Muda","description":"HTTP 202 confirma autenticacao, validacao e persistencia duravel. O efeito no CRM e assincrono.","security":[{"HmacSignature":[]},{"BearerAuth":[]}],"parameters":[{"name":"endpointKey","in":"path","required":true,"schema":{"type":"string"},"description":"Chave publica exibida na configuracao do endpoint."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookEnvelope"},{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/WebhookEnvelope"}}]},"examples":{"lead":{"summary":"Lead basico","value":{"id":"partner_lead_12345_created_1784574000","type":"lead.added","version":"2026-07-01","occurred_at":"2026-07-20T14:30:00.000Z","source":"partner_system","data":{"external_id":"lead_12345","name":"Contato de homologacao","phone":"<telefone_internacional_exemplo_+55...>","email":"contato@example.invalid","stage_external_id":"stage_new","custom_fields":{"campaign_name":"Campanha de homologacao","form_name":"Formulario principal"}},"previous":null,"metadata":{"campaign_id":"campaign_synthetic","correlation_id":"correlation_synthetic"}}},"formLead":{"summary":"Lead com respostas de formulario","value":{"id":"form_lead_12345_created_1784574000","type":"lead.added","version":"2026-07-01","occurred_at":"2026-07-20T14:30:00.000Z","source":"lead_form","data":{"external_id":"form_lead_12345","name":"Contato de homologacao","email":"contato@example.invalid","phone":"<telefone_internacional_exemplo_+55...>","description":"Cargo: Gestor\nUnidades: 2\nPrazo: Nos proximos 30 dias\nOrganizacao atual: Planilhas e mensagens","custom_fields":{"cargo":"Gestor","unidades":2,"prazo":"Nos proximos 30 dias","organizacao_atual":"Planilhas e mensagens"}},"previous":null,"metadata":{"form_id":"form_synthetic","campaign_id":"campaign_synthetic"}}}}}}},"responses":{"202":{"description":"Evento autenticado, validado e persistido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedReceipt"}}}},"400":{"description":"JSON malformado."},"401":{"description":"Credencial ou assinatura invalida."},"404":{"description":"Endpoint inexistente, pausado ou revogado."},"408":{"description":"Corpo nao chegou dentro do prazo de leitura."},"409":{"description":"Mesmo id reutilizado com um payload diferente."},"413":{"description":"Corpo acima do limite do endpoint."},"415":{"description":"Content-Type diferente de application/json."},"422":{"description":"Envelope, evento, versao ou campos invalidos."},"429":{"description":"Limite de requisicoes atingido; respeite Retry-After."},"503":{"description":"Persistencia temporariamente indisponivel."}}}}},"components":{"securitySchemes":{"HmacSignature":{"type":"apiKey","in":"header","name":"X-Muda-Signature","description":"t=<unix_seconds>,v1=<hmac_sha256_hex>"},"BearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"WebhookEnvelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://web.muda.chat/developers/webhooks/schema.json","title":"Muda webhook event envelope","description":"Contrato JSON v1 para eventos recebidos pelo Muda. O servidor tambem limita a arvore a 8 niveis, 300 chaves/itens customizados e strings a 16384 caracteres, alem de rejeitar occurred_at alem da tolerancia futura.","type":"object","additionalProperties":false,"required":["id","type","version","occurred_at","source","data"],"properties":{"id":{"type":"string","minLength":1,"maxLength":240},"type":{"type":"string","enum":["lead.added","lead.updated","lead.deleted","lead.restored","lead.stage_changed","lead.responsible_changed","contact.added","contact.updated","contact.deleted","contact.restored","contact.responsible_changed","company.added","company.updated","company.deleted","company.restored","company.responsible_changed","task.added","task.updated","task.deleted","task.responsible_changed","incoming_lead.added","incoming_lead.updated","incoming_lead.deleted","message.incoming","talk.added","talk.updated","note.lead_added","note.contact_added","note.company_added","product.added","product.updated","product.deleted"]},"version":{"const":"2026-07-01"},"occurred_at":{"type":"string","format":"date-time"},"source":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]*$","description":"Identificador informativo do emissor. O Muda registra a origem confiavel do endpoint autenticado."},"data":{"type":"object","additionalProperties":true,"required":["external_id"],"properties":{"external_id":{"oneOf":[{"type":"string","minLength":1,"maxLength":240,"pattern":"\\S"},{"type":"number"}],"description":"Identificador estavel da entidade no sistema de origem."},"name":{"type":["string","null"],"maxLength":500},"phone":{"type":["string","null"],"maxLength":80,"description":"Telefone internacional valido no formato E.164, incluindo o codigo do pais (por exemplo, +<codigo_pais><numero>)."},"email":{"type":["string","null"],"maxLength":320},"description":{"description":"Resumo recomendado para leitura humana. O contrato aceita qualquer valor JSON neste campo customizado."},"custom_fields":{"description":"Respostas estruturadas ou campos do sistema de origem. O contrato aceita qualquer valor JSON."}}},"previous":{"type":["object","null"],"additionalProperties":true},"metadata":{"type":"object","additionalProperties":true,"propertyNames":{"maxLength":120},"default":{}}},"examples":[{"id":"partner_lead_12345_created_1784574000","type":"lead.added","version":"2026-07-01","occurred_at":"2026-07-20T14:30:00.000Z","source":"partner_system","data":{"external_id":"lead_12345","name":"Contato de homologacao","phone":"<telefone_internacional_exemplo_+55...>","email":"contato@example.invalid","stage_external_id":"stage_new","custom_fields":{"campaign_name":"Campanha de homologacao","form_name":"Formulario principal"}},"previous":null,"metadata":{"campaign_id":"campaign_synthetic","correlation_id":"correlation_synthetic"}},{"id":"form_lead_12345_created_1784574000","type":"lead.added","version":"2026-07-01","occurred_at":"2026-07-20T14:30:00.000Z","source":"lead_form","data":{"external_id":"form_lead_12345","name":"Contato de homologacao","email":"contato@example.invalid","phone":"<telefone_internacional_exemplo_+55...>","description":"Cargo: Gestor\nUnidades: 2\nPrazo: Nos proximos 30 dias\nOrganizacao atual: Planilhas e mensagens","custom_fields":{"cargo":"Gestor","unidades":2,"prazo":"Nos proximos 30 dias","organizacao_atual":"Planilhas e mensagens"}},"previous":null,"metadata":{"form_id":"form_synthetic","campaign_id":"campaign_synthetic"}}]},"AcceptedReceipt":{"type":"object","additionalProperties":false,"required":["received","accepted","duplicates","request_id"],"properties":{"received":{"type":"boolean","const":true},"accepted":{"type":"integer","minimum":0},"duplicates":{"type":"integer","minimum":0},"request_id":{"type":"string"}}}}}}