# 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.
",
"attachments": []
}
],
"transactional_whatsapp_sent": [],
"comments": [
{
"from_customer": false,
"read": true,
"notify_customer": false,
"_id": "abc123def456ghi789jkl023",
"user": "T&D - Automação - bling",
"comment": "Atualização de rastreamento: Pedido entregue em 18/11/2025 - Transportadora Expresso - Código de Rastreamento EXP987654",
"created_at": "2025-11-24T14:20:15-03:00",
"read_at": "2025-11-24T14:20:15-03:00",
"attachments": [],
"users_mentioned": []
},
{
"from_customer": false,
"read": true,
"notify_customer": false,
"_id": "abc123def456ghi789jkl024",
"user": "T&D - Automação",
"comment": "Vale-trocas emitido automaticamente na plataforma Shopify no valor de R$ 247,40 com validade até 15/06/2031 23:59. O código do vale-trocas é: TEDEXEMPLO123",
"created_at": "2025-11-28T09:15:30-03:00",
"read_at": "2025-11-28T09:15:30-03:00",
"attachments": [],
"users_mentioned": []
}
],
"nps_surveys": [],
"webhooks": [
{
"attempt": 1,
"success": true,
"_id": "abc123def456ghi789jkl025",
"url": "https://webhook.exemplo.com.br/troca-devolucao",
"method": "POST",
"headers": {
"Content-Type": "application/json"
},
"responseCode": 200,
"responseBody": {
"message": "Workflow was started"
},
"duration": 452,
"event": "request.posted"
}
],
"createdAt": "2025-11-24T14:20:10-03:00",
"updatedAt": "2025-12-15T10:35:20-03:00",
"__v": 5,
"voucher_code_example": "TEDEXEMPLO123",
"id": "abc123def456ghi789jkl017"
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.troqueedevolva.com.br/configuracoes/webhooks.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.