# Webhooks
## Criando um Webhook
Um **webhook** é uma forma de integrar sistemas diferentes, permitindo que informações sejam enviadas automaticamente de uma aplicação para outra quando algo acontece.
Na prática, ele funciona como uma notificação: quando um evento específico ocorre (como a criação de uma solicitação), o webhook envia os dados para uma URL configurada.
Na nossa plataforma, você pode configurar webhooks para eventos como:
* **request.created:** Nova solicitação criada.
* **request.rejected:** Solicitação rejeitada.
* **request.authorized:** Solicitação autorizada.
* **request.posted:** Solicitação postada.
* **request.delivered:** Solicitação entregue.
* **request.done:** Solicitação concluída.
Dentro do painel Troque & Devolva, acesse **Configurações > Webhooks**. Será mostrada a listagem de eventos já existentes.
Listagem de webhooks configurados na Troque & Devolva
Para criar um novo, clique no botão **Novo Webhook** e preencha as informações em tela.
Para configurar, você só precisa informar a URL que receberá os dados, selecionar os eventos desejados e, se necessário, adicionar headers e escolher o método de envio (geralmente POST).
Exemplo de tela de configuração de Webhook
## Dados enviados na chamada do Webhook
Ao receber o webhook, a depender de cada um dos eventos que você configurar, poderão ser enviados mais ou menos dados preenchidos. O ideal é que você realize testes.
De todo modo, a estrutura é semelhante a esse json:
```json
{
"order": {
"invoice": {
"series": "1",
"type": "out",
"number": "100234",
"key": "35251298765432100198550010001002341234567890",
"erp_id": "98765432100",
"erp_reference": "bling",
"danfe_link": "https://www.bling.com.br/doc.view.php?id=abc123def456ghi789jkl012mno345pq",
"link": "https://www.bling.com.br/relatorios/nfe.xml.php?chaveAcesso=35251298765432100198550010001002341234567890&s&signature=abc123def456ghi789jkl012mno345pqrst678uvwxyz901234567890abcdef12"
},
"buyer": {
"document": {
"number": "12345678900",
"type": "cpf"
},
"address": {
"country": "brasil",
"address": "Rua das Flores",
"number": "456",
"address2": "Apto 101",
"postal_code": "01234567",
"neighborhood": "Jardim Primavera",
"city": "São Paulo",
"state": "SP"
},
"id": "1234567890123",
"name": "Maria Fernanda Santos",
"email": "maria.fernanda@exemplo.com.br",
"mobile": "+5511987654321"
},
"shippment": {
"destination": {
"country": "brasil"
},
"last_delivered": true,
"last_delivered_at": "2025-11-18T14:22:00-03:00",
"packages": [
{
"delivered": true,
"_id": "abc123def456ghi789jkl012",
"carrier": "Expresso",
"tracking_number": "EXP987654",
"delivered_at": "2025-11-18T14:22:00-03:00",
"tracking_details": {
"codigo": "EXP987654",
"descricao": "Entrega realizada",
"situacao": 3,
"origem": "Entrega realizada com sucesso!",
"destino": "",
"ultimaAlteracao": "2025-11-18 17:22:00",
"url": "https://rastreamento.exemplo.com.br/busca"
}
}
]
},
"discount": 0,
"tax": 0,
"total_products": 247.40,
"total_shipping": 12.50,
"free_shipping": false,
"created_at": "2025-11-05T10:15:30-03:00",
"order_id": "1234567890123",
"order_number": "5001234",
"total_tax": 0,
"total": 259.90,
"discount_voucher": "",
"payment": [
{
"name": "Cartão de Crédito",
"method": "Cartão de Crédito",
"_id": "abc123def456ghi789jkl001",
"amount": 259.90,
"detail": "paid"
}
],
"cart_items": [
{
"cannot_exchange": false,
"cannot_return": false,
"cannot_warranty": false,
"total_price": 247.40,
"discount": 0,
"discount_percentage": 0,
"shared_discount": 0,
"shared_discount_percentage": 0,
"individual_discount": 0,
"price": 247.40,
"_id": "abc123def456ghi789jkl002",
"sku": "SKU123456789",
"image": "https://cdn.exemplo.com/images/produto-vestido-floral.jpg",
"link": "https://loja.exemplo.com.br/products/vestido-longo-floral",
"name": "Vestido Longo Estampado Floral Verão - G",
"quantity": 1,
"length": 0,
"width": 0,
"height": 0,
"weight": 350,
"shipping_cost_share": 12.50,
"kit_sku": []
}
]
},
"request": {
"payment_preference": {
"additional_credit_percentage": 0,
"additional_credit_amount": 0,
"additional_accepted_popup": false,
"additional_accepted_email": false,
"type": "voucher"
},
"partial": false,
"items": [
{
"stock": {
"issue": {
"attachments": []
},
"received": true,
"received_quantity": 1,
"status": "received",
"disposal": null,
"received_date": "2025-12-15T10:30:45-03:00",
"checked_by_user": "Conferência"
},
"cannot_exchange": false,
"cannot_return": false,
"cannot_warranty": false,
"discount": 0,
"discount_percentage": 0,
"shared_discount": 0,
"shared_discount_percentage": 0,
"individual_discount": 0,
"_id": "abc123def456ghi789jkl003",
"sku": "SKU123456789",
"image": "https://cdn.exemplo.com/images/produto-vestido-floral.jpg",
"link": "https://loja.exemplo.com.br/products/vestido-longo-floral",
"name": "Vestido Longo Estampado Floral Verão - G",
"quantity": 1,
"price": 247.40,
"total_price": 247.40,
"length": 0,
"width": 0,
"height": 0,
"weight": 350,
"shipping_cost_share": 12.50,
"questions": [
{
"options": [],
"_id": "abc123def456ghi789jkl004",
"required": true,
"area": "exchange",
"question": "Qual o motivo da troca?",
"value": "Tamanho não serviu",
"attachments": []
}
],
"type": "exchange",
"kit_sku": [],
"attachments": []
}
]
},
"process": {
"locked_return_center": {
"is_locked": false
},
"last_status": {
"expectAttachments": false,
"to": 5,
"user": "T&D - Automação",
"from": 34,
"message": "Seu vale-trocas no valor de R$ 247,40 foi emitido e você tem até 15/06/2031 23:59 para realizar sua nova compra. O código do vale-trocas é: TEDEXEMPLO123",
"updated_at": "2025-12-15T10:30:45-03:00"
},
"refund_options": {
"add_shipping_cost": false,
"add_discount": false
},
"voucher_details": {
"user": "T&D - Automação",
"integration_id": "abc123def456ghi789jkl005",
"integration_reference": "shopify",
"created_at": "2025-11-28T09:15:30-03:00",
"voucher_code": "TEDEXEMPLO123",
"valid_until": "2031-06-15T23:59:59-03:00",
"amount": 247.40
},
"return_invoice": {
"invoice": {
"invoice_id": "12345678901",
"number": "100567",
"series": "1",
"key": "35251298765432100198550010001005671234567890"
},
"invoiced": true,
"authorized": true,
"triggered": "manual",
"pdf": "https://www.bling.com.br/doc.view.php?PDF=true&id=xyz789abc123def456ghi789jkl012mno",
"xml": "https://www.bling.com.br/relatorios/nfe.xml.php?chaveAcesso=35251298765432100198550010001005671234567890&s&signature=xyz789abc123def456ghi789jkl012mno345pqrst678uvwxyz901234567890xyz",
"created_at": "2025-12-15T10:35:20-03:00",
"integration_id": "abc123def456ghi789jkl006",
"integration_reference": null,
"user": "system",
"items": []
},
"received_items": {
"done": true,
"disposal": null,
"auto_authorization_log": [],
"done_at": "2025-12-15T10:30:45-03:00",
"user": "Conferência",
"amount": 247.40,
"shipping_cost": 12.50,
"disposal_reason": null
},
"waiting_customer_bank_account": false,
"status": 5,
"status_history": [
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl007",
"to": 0,
"user": "Maria Fernanda Santos",
"from": 0,
"message": "solicitação criada",
"updated_at": "2025-11-24T14:20:10-03:00",
"updated_at_BR": "24/11/2025, 14:20",
"type": "status",
"to_translated": "Nova solicitação"
},
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl008",
"to": 11,
"user": "T&D - Automação",
"from": 0,
"message": "Autorização de postagem emitida em 24/11/2025 14:25 | Transportador Correios | Código de Autorização - Rastreamento Nº BR123456789XX | Validade para postagem até 04/12/2025 | Retorno para o centro para devolução Centro Distribuição SP",
"updated_at": "2025-11-24T14:25:15-03:00",
"updated_at_BR": "24/11/2025, 14:25",
"type": "status",
"to_translated": "Aguardando postagem"
},
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl009",
"to": 12,
"user": "api",
"from": 11,
"message": "Autorização de postagem utilizada pelo cliente em 26/11/2025 10:45 | Código de rastreamento BR123456789XX | Valor da postagem R$ 58,90",
"updated_at": "2025-11-26T13:45:30-03:00",
"updated_at_BR": "26/11/2025, 13:45",
"type": "status",
"to_translated": "Em transporte"
},
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl010",
"to": 13,
"user": "api",
"from": 12,
"message": "Recebido no centro de retorno Centro Distribuição SP em 08/12/2025 09:15.",
"updated_at": "2025-12-08T12:15:45-03:00",
"updated_at_BR": "08/12/2025, 12:15",
"type": "status",
"to_translated": "Para conferência"
},
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl011",
"to": 34,
"from": 13,
"user": "Conferência",
"message": "Itens recebidos, aguardando análise de pagamento",
"updated_at": "2025-12-15T10:30:45-03:00",
"updated_at_BR": "15/12/2025, 10:30",
"type": "status",
"to_translated": "Para pagamento"
},
{
"expectAttachments": false,
"_id": "abc123def456ghi789jkl012",
"to": 5,
"user": "T&D - Automação",
"from": 34,
"message": "Seu vale-trocas no valor de R$ 247,40 foi emitido e você tem até 15/06/2031 23:59 para realizar sua nova compra. O código do vale-trocas é: TEDEXEMPLO123",
"updated_at": "2025-12-15T10:30:45-03:00",
"updated_at_BR": "15/12/2025, 10:30",
"type": "status",
"to_translated": "Concluída"
}
],
"shippment_authorization": [
{
"quotation": {
"width": 25,
"height": 15,
"length": 40,
"weight": 1000,
"estimated_price": 58.90,
"delivery_days": 7,
"service": "PAC",
"raw_data": {
"price": 58.90,
"shipping_service": {
"name": "PAC",
"code": "03301"
},
"description": "",
"delivery_days": 7,
"carrier_reference": "correios"
}
},
"own_issuer": true,
"posting_method": "customer_dropoff",
"canceled": false,
"posted": true,
"delivered": true,
"requires_label_print": false,
"waiting_for_label": false,
"log": [
"Data da solicitação: 23/11/2025",
"Data da entrega do pedido: 17/11/2025",
"Autorização automática para troca está ativada.",
"Motivo (Tamanho não serviu) permitido para troca.",
"Dias decorridos desde a entrega: 6, Prazo para troca: 90 dias",
"Valor total dos produtos: R$ 247.40",
"Transportadora selecionada: Correios PAC (PAC)",
"Prazo de entrega: 7 dias",
"Centro de retorno selecionado: Minha Loja Moda"
],
"_id": "abc123def456ghi789jkl013",
"own_authorization_issuer": "abc123def456ghi789jkl014",
"created_at": "2025-11-24T14:25:15-03:00",
"carrier": "Correios",
"shipping_instructions": "
Vá até uma agência dos Correios, informe que é logística reversa e apresente o código.
