POST para URLs cadastradas sempre que determinados eventos ocorrerem. O payload enviado contém todas as includes disponíveis relacionadas ao recurso.
Crie webhooks via API
Você pode criar e gerenciar webhooks através da API de Webhooks. Para mais informações, consulte a documentação da API de Webhooks.A criação dos webhooks é restrita ao limite definido ao plano da sua loja, acesse a página de planos para consultar seu limite.
Webhooks criados por aplicativos homologados não são levados em consideração nessa contagem.
Eventos disponíveis
Abaixo estão os eventos atualmente suportados. Você pode configurar webhooks para escutar um ou mais desses eventos:| Evento | Descrição | Exemplos |
|---|---|---|
| order.created | Pedido criado | Ver payload |
| order.paid | Pedido aprovado | Ver payload |
| order.status.updated | O status de um pedido foi atualizado | Ver payload |
| order.invoice.created | Nota fiscal de um pedido foi criada | Ver payload |
| order.invoice.updated | Nota fiscal de um pedido foi atualizada | Ver payload |
| transaction.payment.refused | O pagamento de uma transação foi negado | Ver payload |
| cart.reminder | Notificação de carrinho abandonado | Ver payload |
| customer.created | Cliente criado | Ver payload |
| customer.address.created | Endereço do cliente criado | Ver payload |
| product.created | Produto criado | Ver payload |
| product.updated | Produto atualizado | Ver payload |
| product.deleted | Produto excluído | Ver payload |
| product.inventory.updated | Estoque de produto atualizado | Ver payload |
| cashback.expiring | Um Cashback está expirando | Ver payload |
Exemplos de payloads de Webhook
Aqui centralizaremos todos os payloads retornados por cada webhook.- Pedidos
- Carrinhos abandonados
- Clientes
- Endereços de clientes
- Produtos
- Cashback
- Transações
- Notas fiscais
- Estoque
Exemplos de payloads retornados em
order.created, order.updated, order.paid e order.status.updated.
Onde, o campo event é enviado de acordo com o evento que disparou esse webhook.{
"event": "", // `order.created`, `order.updated`, `order.paid` ou `order.status.updated`
"time": "2025-01-01 12:00:00",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 1000001,
"merchant_id": 123,
"customer_id": 987654,
"status_id": 3,
"desire_status_id": [8, 4, 9],
"desire_status": ["cancelled", "paid", "refused"],
"promocode_id": null,
"marketplace_id": null,
"marketplace_account_id": null,
"authorized": false,
"sync_by_erp": false,
"has_recomm": false,
"has_upsell": false,
"has_freebie": false,
"has_order_bump": false,
"order_bump_types": [],
"has_payment": true,
"is_upsell": false,
"delivered": false,
"number": 123456789012,
"value_total": 199.90,
"buyer_value_total": 199.90,
"value_products": 180,
"value_shipment": 19.90,
"value_tax": 0,
"buyer_value_tax": 0,
"value_discount": 10,
"value_wallet_discount": 0,
"shipment_cost": 19.90,
"shipment_service": "CORREIOS_PAC",
"shipment_service_id": "12345",
"shipment_icon_url": null,
"shipment_quote_id": "abc123",
"track_code": null,
"track_url": null,
"days_delivery": 7,
"date_delivery": {
"date": "2025-01-08 00:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"cart_token": "cart-token-exemplo",
"utm_source": null,
"utm_campaign": null,
"utm_content": null,
"utm_term": null,
"utm_medium": null,
"total_comments": 0,
"payments": [
{
"alias": "credit_card",
"name": "Cartão de Crédito",
"icon_url": "https://icons.exemplo.com/svg/credit-card.svg"
}
],
"ip": "192.168.0.1",
"device": "desktop",
"reorder_url": "https://lojaexemplo.com.br/checkout?token=cliente123",
"content_statement_url": "https://api.exemplo.com.br/orders/content-statement/abc123",
"billet_whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000&text=",
"billet_whatsapp_app_link": "whatsapp://send?phone=5500000000000&text=",
"public_url": "https://api.exemplo.com.br/public/orders/abc123",
"created_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"status": {
"data": {
"id": 3,
"alias": "waiting_payment",
"name": "Aguardando pagamento",
"description": "Aguardando confirmação de pagamento"
}
},
"customer": {
"data": {
"id": 987654,
"merchant_id": 123,
"type": "f",
"name": "Cliente Exemplo",
"first_name": "Cliente",
"last_name": "Exemplo",
"email": "cliente@exemplo.com",
"cpf": "00000000000",
"birthday": "1990-01-01",
"phone": {
"full_number": "5500000000000",
"area_code": "00",
"number": "000000000",
"formated_number": "(00) 00000-0000",
"whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000"
},
"ip": "192.168.0.1",
"token": "cliente-token-exemplo",
"login_url": "https://lojaexemplo.com.br/auth/login?token=cliente-token-exemplo",
"anonymized": false,
"created_at": {
"date": "2022-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 11:59:59.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"items": {
"data": [
{
"id": 111,
"product_id": 5555,
"sku_id": 7777,
"price_cost": 150,
"price": 180,
"item_sku": "SKU123456",
"quantity": 1,
"shipment_cost": 19.90,
"gift": false,
"customizations": [],
"is_digital": false,
"sku": {
"data": {
"id": 7777,
"product_id": 5555,
"sku": "SKU123456",
"token": "sku-token-exemplo",
"title": "Produto Exemplo",
"price_cost": 150,
"price_sale": 180,
"price_discount": 10,
"purchase_url": "https://lojaexemplo.com.br/produto/sku-token-exemplo",
"customizations": { "data": [] }
}
}
}
]
},
"transactions": {
"data": [
{
"id": 9999,
"customer_id": 987654,
"payment_id": 1,
"authorized": true,
"captured": true,
"amount": 199.90,
"installments": 1,
"installment_value": 199.90,
"status": "paid",
"created_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"payment": {
"data": {
"id": 1,
"alias": "credit_card",
"name": "Cartão de Crédito",
"is_credit_card": true,
"icon_url": "https://icons.exemplo.com/svg/credit-card.svg"
}
}
}
]
},
"shipping_address": {
"data": {
"receiver": "Cliente Exemplo",
"zipcode": "00000000",
"street": "Rua Exemplo",
"number": "123",
"neighborhood": "Bairro Exemplo",
"city": "Cidade Exemplo",
"state": "EX",
"country": "BR"
}
},
"statuses": {
"data": [
{
"id": 3,
"alias": "waiting_payment",
"name": "Aguardando pagamento",
"description": "Aguardando confirmação de pagamento",
"created_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 12:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
]
},
"metadata": {
"data": [
{ "key": "cart_id", "value": "123456" },
{ "key": "source_platform", "value": "checkout_link" }
]
},
"spreadsheet": {
"data": [
{
"product": "Produto Exemplo",
"sku": "SKU123456",
"quantity": 1,
"total_cost": 150,
"total_item": 180,
"payment_date": "01/01/2025 12:00",
"customer": "Cliente Exemplo",
"customer_email": "cliente@exemplo.com",
"customer_phone": "00000000000",
"status": "Pagamento aprovado",
"payment": "Cartão de Crédito",
"shipping_address": "Rua Exemplo, 123 - Bairro Exemplo",
"shipping_city": "Cidade Exemplo",
"shipping_state": "Estado Exemplo",
"shipping_zip_code": "00000000"
}
]
}
}
}
Exemplo de payload retornados em
cart.reminder.{
"event": "cart.reminder",
"time": "2025-01-01 10:40:38",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 111111111,
"merchant_id": 123,
"customer_id": 999999,
"token": "cart-token-exemplo",
"payment_alias": null,
"has_recommendation": false,
"is_upsell": false,
"totalizers": {
"total_items": 1,
"subtotal": 20,
"discount": 0,
"shipment": 9.16,
"shipment_original_value": 9.16,
"shipment_discount_value": 0,
"shipment_discount_percent": 0,
"progressive_discount_value": 0,
"combos_discount_value": 0,
"total": 29.16,
"shipment_formated": "R$ 9,16",
"subtotal_formated": "R$ 20,00",
"discount_formated": "R$ 0,00",
"total_formated": "R$ 29,16"
},
"shipping_service": "CORREIOS_PAC",
"tracking_data": {
"name": "João da Silva",
"email": "joao@email.com"
},
"total_transactions": 0,
"simulate_url": "https://lojaexemplo.com.br/cart?cart_token=cart-token-exemplo&customerToken=cliente-token",
"unauth_simulate_url": "https://lojaexemplo.com.br/cart?cart_token=cart-token-exemplo&forceLogout=1",
"utm_source": null,
"utm_campaign": null,
"utm_content": null,
"utm_term": null,
"utm_medium": null,
"last_transaction_status": null,
"created_at": {
"date": "2025-01-01 10:37:31.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 10:37:35.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"customer": {
"data": {
"id": 999999,
"merchant_id": 123,
"active": true,
"type": "f",
"name": "João da Silva",
"first_name": "João",
"last_name": "Silva",
"generic_name": "João da Silva",
"email": "joao@email.com",
"cpf": "00000000000",
"birthday": "1990-01-01",
"phone": {
"full_number": "5500000000000",
"area_code": "00",
"number": "000000000",
"formated_number": "(00) 00000-0000",
"whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000"
},
"newsletter": false,
"whatsapp": false,
"ip": "192.168.0.1",
"notes": "Observação exemplo",
"token": "cliente-token",
"login_url": "https://lojaexemplo.com.br/auth/login/force?token=cliente-token",
"anonymized": false,
"created_at": {
"date": "2022-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 10:37:49.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"items": {
"data": [
{
"id": 555555,
"product_id": 111111,
"sku_id": 222222,
"quantity": 1,
"price": 20,
"gift": false,
"has_recomm": false,
"customizations": [],
"created_at": {
"date": "2025-01-01 10:37:32.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 10:37:32.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"sku": {
"data": {
"id": 222222,
"product_id": 111111,
"sku": "SKU123456",
"token": "sku-token-exemplo",
"title": "Produto Exemplo",
"price_cost": 17,
"price_sale": 8,
"price_discount": 20,
"quantity_managed": true,
"total_in_stock": 20,
"purchase_url": "https://lojaexemplo.com.br/r/sku-token-exemplo",
"created_at": {
"date": "2025-01-01 09:24:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 10:13:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"customizations": { "data": [] }
}
}
}
]
},
"transactions": { "data": [] },
"spreadsheet": {
"data": {
"customer_phone": "00000000000",
"last_order_date": "2025-01-01",
"products": "Produto Exemplo",
"products_skus": "SKU123456",
"categories": "Categoria Exemplo",
"brands": "Marca Exemplo",
"purchase_url": "https://lojaexemplo.com.br/cart?cart_token=cart-token-exemplo&forceLogout=1",
"abandoned_step": "shippment",
"count_recover_mail_sent": "0/4"
}
},
"metadata": {
"data": [
{ "key": "discount_highlight", "value": "deposit" },
{ "key": "source_platform", "value": "purchase_link" }
]
},
"search": {
"data": {
"has_shipment_service": true,
"has_address": true,
"has_customer": true,
"has_refused_payment": false,
"abandoned_step": "shippment",
"count_recover_mail_sent": 0,
"created_at": "2025-01-01",
"updated_at": "2025-01-01"
}
},
"emails": {
"data": [
{
"id": 1,
"cart_id": 111111111,
"promocode_id": null,
"turn": 1,
"email": "joao@email.com",
"fire_date": "2025-01-01 10:52:35",
"sent_at": null,
"created_at": "2025-01-01 10:38:52",
"updated_at": "2025-01-01 10:38:52"
},
{
"id": 2,
"cart_id": 111111111,
"promocode_id": null,
"turn": 2,
"email": "joao@email.com",
"fire_date": "2025-01-01 12:37:35",
"sent_at": null,
"created_at": "2025-01-01 10:38:52",
"updated_at": "2025-01-01 10:38:52"
},
{
"id": 3,
"cart_id": 111111111,
"promocode_id": null,
"turn": 3,
"email": "joao@email.com",
"fire_date": "2025-01-02 10:37:35",
"sent_at": null,
"created_at": "2025-01-01 10:38:52",
"updated_at": "2025-01-01 10:38:52"
},
{
"id": 4,
"cart_id": 111111111,
"promocode_id": null,
"turn": 4,
"email": "joao@email.com",
"fire_date": "2025-01-03 10:37:35",
"sent_at": null,
"created_at": "2025-01-01 10:38:52",
"updated_at": "2025-01-01 10:38:52"
}
]
}
}
}
Exemplo de payload retornados em
customer.created.{
"event": "customer.created",
"time": "2025-01-01 15:18:28",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 111111111,
"merchant_id": 123,
"marketplace_id": null,
"cluster_id": 999,
"active": true,
"type": "f",
"name": "João Exemplo",
"razao_social": null,
"first_name": "João",
"last_name": "Exemplo",
"generic_name": "João Exemplo",
"email": "joao@example.com",
"cnpj": null,
"state_registration": null,
"cpf": "00000000000",
"birthday": "1990-01-01",
"phone": {
"full_number": "5500000000000",
"area_code": "00",
"number": "000000000",
"formated_number": "(00) 00000-0000",
"whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000"
},
"social_driver": null,
"social_id": null,
"newsletter": false,
"whatsapp": false,
"utm_source": null,
"utm_campaign": null,
"ip": null,
"notes": null,
"token": "cliente-token-exemplo",
"login_url": "https://lojaexemplo.com.br/auth/login/force?token=cliente-token-exemplo",
"anonymized": false,
"created_at": {
"date": "2025-01-01 15:18:17.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 15:18:17.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"stats": {
"data": {
"orders_amount": 0,
"total_orders": 0,
"last_order_at": null,
"last_order_id": null,
"last_order_number": null,
"last_order_amount": null,
"total_carts": 0,
"purchased_categories": [],
"purchased_brands": []
}
},
"addresses": {
"data": []
},
"cluster": {
"data": {
"id": 999,
"name": "pessoa física",
"active": true,
"attach_on_signup": false,
"person_type": "f",
"min_order_value": "1.00",
"base_price_percent": 0,
"payments_ids": [1, 2, 3],
"carriers_ids": [1001, 1002, 1003],
"created_at": {
"date": "2025-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 11:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"spreadsheet": {
"data": {
"last_order_value": "",
"last_order_date": [],
"categories": "",
"brands": "",
"street": "",
"number": "",
"neighborhood": "",
"complement": "",
"city": "",
"uf": "",
"purchased_categories": "",
"purchased_brands": "",
"phone_code": "00",
"phone_number": "000000000",
"phone": "(00) 00000-0000"
}
},
"search": {
"data": {
"last_order_at": null,
"created_at": "2025-01-01",
"updated_at": "2025-01-01",
"total_orders": 0,
"states": [],
"purchased_products_ids": []
}
},
"deletion_request": {
"data": {
"pending_confirmation": false,
"scheduled_date": ""
}
}
}
}
Exemplo de payload retornados em
customer.address.created.{
"event": "customer.address.created",
"time": "2025-05-16 13:59:45",
"merchant": {
"id": 999,
"alias": "loja-exemplo"
},
"resource": {
"id": 100000001,
"customer_id": 200000002,
"receiver": "João Exemplo",
"zip_code": "12345678",
"street": "Rua Exemplo",
"number": "123",
"neighborhood": "Bairro Central",
"complement": "Apto 45B",
"city": "Cidade Modelo",
"uf": "EX",
"full_address": "Rua Exemplo, 123 - Bairro Central",
"created_at": {
"date": "2025-05-16 13:59:35.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-05-16 13:59:35.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
}
Exemplo de payload retornados em
product.created e product.updated.{
"event": "product.created",
"time": "2025-05-15 09:24:25",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"relevance": null,
"id": 10001,
"merchant_id": 123,
"seller_id": null,
"affiliation_id": null,
"active": true,
"gift_value": "0.00",
"searchable": true,
"simple": true,
"erp_id": null,
"ncm": null,
"has_variations": false,
"is_digital": false,
"warranty": 0,
"custom_shipping": false,
"shipping_price": "0.00",
"name": "Produto Exemplo Webhook",
"slug": "produto-exemplo-webhook",
"sku": "",
"rating": 0,
"priority": 1,
"url": "https://www.lojavirtual.com/produto-exemplo-webhook/p",
"redirect_url_card": null,
"redirect_url_billet": null,
"preview_url": "https://lojaexemplo.catalog.yampi.io/produto-exemplo-webhook/p",
"dates": {
"data": {
"created_at": {
"date": "2025-05-15 09:24:14.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"created_at_formated": "2025-05-15",
"updated_at": {
"date": "2025-05-15 09:24:14.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"brand": {
"data": {
"id": 100,
"active": true,
"featured": false,
"name": "Marca Genérica",
"description": null,
"logo_url": null,
"created_at": {
"date": "2020-01-01 00:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2020-01-01 00:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"filters": {
"data": []
},
"flags": {
"data": []
},
"variations": {
"data": []
},
"categories": {
"data": [
{
"id": 200,
"name": "Categoria Genérica",
"parent_id": null,
"slug": "categoria-generica",
"url_path": "/categoria-generica"
}
]
},
"skus": {
"data": [
{
"id": 9999,
"product_id": 10001,
"seller_id": null,
"sku": "SKU123456",
"token": "TOKEN123456",
"erp_id": null,
"blocked_sale": false,
"barcode": null,
"title": "Produto Exemplo Webhook",
"availability": 0,
"availability_soldout": -1,
"days_availability_formated": "Imediata",
"price_cost": 10,
"price_sale": 15,
"price_discount": 20,
"width": 0,
"height": 0,
"length": 0,
"weight": 0,
"quantity_managed": false,
"variations": [],
"combinations": "9999",
"order": 0,
"total_in_stock": 0,
"total_orders": null,
"allow_sell_without_customization": false,
"image_reference_sku_id": null,
"purchase_url": "https://lojaexemplo.pay.yampi.com.br/r/TOKEN123456",
"created_at": {
"date": "2025-05-15 09:24:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-05-15 09:24:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"images": {
"data": [
{
"id": 999001,
"processed": true,
"name": "produto-exemplo-webhook-1",
"order": 0,
"extension": "png",
"filter_image_url": null,
"small": {
"width": 50,
"height": 50,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-small.png"
},
"thumb": {
"width": 250,
"height": 250,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-thumb.png"
},
"medium": {
"width": 500,
"height": 500,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-medium.png"
},
"large": {
"width": 1000,
"height": 1000,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-large.png"
}
}
]
}
}
]
},
"firstImage": {
"data": {
"id": 999001,
"processed": true,
"name": "produto-exemplo-webhook-1",
"order": 0,
"extension": "png",
"filter_image_url": null,
"small": {
"width": 50,
"height": 50,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-small.png"
},
"thumb": {
"width": 250,
"height": 250,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-thumb.png"
},
"medium": {
"width": 500,
"height": 500,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-medium.png"
},
"large": {
"width": 1000,
"height": 1000,
"url": "https://images.yampi.me/assets/stores/lojaexemplo/uploads/images/produto-exemplo-webhook-1-large.png"
}
}
}
}
}
Exemplo de payload retornados em
cashback.expiring. Esses webhooks são enviados 7 dias antes do cashback expirar.{
"event": "cashback.expiring",
"time": "2025-05-16T14:34:02-03:00",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 100001,
"transaction_type": "credit",
"amount": 2.72,
"status": "approved",
"expired": false,
"description": null,
"expires_at": "2025-05-23",
"customer": {
"id": 99999999,
"name": "Nome Sobrenome",
"email": "email@email.com",
"phone": "5500000000000"
},
"order": {
"id": 200001,
"number": 999999999999
},
"created_at": {
"date": "2025-05-15 09:42:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-05-15 09:42:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
}
Exemplo de payload retornados em
transaction.payment.refused.{
"event": "transaction.payment.refused",
"time": "2025-01-01 09:33:37",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 111111,
"customer_id": 999999,
"payment_id": 9,
"affiliation_id": 555555,
"marketplace_id": null,
"marketplace_account_id": null,
"authorized": false,
"captured": false,
"cancelled": true,
"gateway_transaction_id": "",
"gateway_order_id": null,
"gateway_authorization_code": null,
"gateway_billet_id": null,
"amount": 29.16,
"buyer_amount": 0,
"installments": 1,
"installment_value": 29.16,
"buyer_installment_value": 0,
"installment_formated": "1x de R$ 29,16",
"buyer_installment_formated": "1x de R$ 0,00",
"bank_name": null,
"bank_alias": null,
"status": "refused",
"error_message": "Authorization has been denied for this request.",
"error_code": 5,
"truncated_card": null,
"holder_name": null,
"holder_document": null,
"billet_url": null,
"billet_barcode": null,
"billet_date": null,
"billet_our_number": null,
"billet_document_number": null,
"billet_whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000&text=",
"antifraud_sale_id": null,
"antifraud_status": null,
"antifraud_score": null,
"sent_to_antifraud": false,
"total_logs": 0,
"capture_date": null,
"authorized_at": null,
"captured_at": null,
"cancelled_at": {
"date": "2025-01-01 09:33:24.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"can_be_captured": false,
"can_be_cancelled": false,
"created_at": {
"date": "2025-01-01 09:33:24.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 09:33:24.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"payment": {
"data": {
"id": 9,
"alias": "billet",
"name": "Boleto Bancário",
"has_config": false,
"active_config": false,
"is_credit_card": false,
"is_deposit": false,
"is_billet": true,
"is_pix": false,
"is_pix_in_installments": false,
"is_wallet": false,
"icon_url": "https://icons.yampi.me/svg/card-billet.svg"
}
},
"metadata": { "data": [] },
"affiliation": {
"data": {
"id": 555555,
"auto_capture": true,
"backup": false,
"force_minimum_tax": false,
"has_payment_config": true,
"name": "Gateway Exemplo",
"statement_descriptor": "exemplo",
"active": true,
"params": [],
"status": "revoked",
"auth_type": "api_key",
"created_at": {
"date": "2023-01-01 09:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2023-01-01 17:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"gateway": {
"data": {
"alias": "gatewayalias",
"icon_url": "https://icons.yampi.me/svg/gateway.svg",
"name": "Gateway Exemplo",
"allow_backup": true,
"credit_card": true,
"installments_config": {
"allow_custom_installments": true,
"message": null,
"help_link": null
},
"auth_type": "api_key",
"gateway_exists": false,
"params": { "data": ["consumer_secret", "public_key"] }
}
}
}
},
"customer": {
"data": {
"id": 999999,
"merchant_id": 123,
"active": true,
"type": "f",
"name": "João da Silva",
"first_name": "João",
"last_name": "Silva",
"generic_name": "João da Silva",
"email": "joao@email.com",
"cpf": "00000000000",
"birthday": "1990-01-01",
"phone": {
"full_number": "5500000000000",
"area_code": "00",
"number": "000000000",
"formated_number": "(00) 00000-0000",
"whatsapp_link": "https://api.whatsapp.com/send?phone=5500000000000"
},
"newsletter": false,
"whatsapp": false,
"ip": "192.168.0.1",
"notes": null,
"token": "cliente-token",
"login_url": "https://lojaexemplo.com.br/auth/login/force?token=cliente-token",
"anonymized": false,
"created_at": {
"date": "2022-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 09:31:58.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
},
"cart": {
"data": {
"id": 888888,
"merchant_id": 123,
"customer_id": 999999,
"token": "cart-token-exemplo",
"payment_alias": "pix",
"has_recommendation": false,
"is_upsell": false,
"totalizers": {
"total_items": 1,
"subtotal": 20,
"discount": 1,
"shipment": 9.16,
"shipment_original_value": 9.16,
"shipment_discount_value": 0,
"shipment_discount_percent": 0,
"progressive_discount_value": 0,
"combos_discount_value": 0,
"total": 28.16,
"shipment_formated": "R$ 9,16",
"subtotal_formated": "R$ 20,00",
"discount_formated": "R$ 1,00",
"total_formated": "R$ 28,16"
},
"shipping_service": "CORREIOS_PAC",
"tracking_data": {
"name": "João da Silva",
"email": "joao@email.com"
},
"total_transactions": 2,
"simulate_url": "https://lojaexemplo.com.br/cart?cart_token=cart-token-exemplo&customerToken=cliente-token",
"unauth_simulate_url": "https://lojaexemplo.com.br/cart?cart_token=cart-token-exemplo&forceLogout=1",
"utm_source": null,
"utm_campaign": null,
"utm_content": null,
"utm_term": null,
"utm_medium": null,
"last_transaction_status": {
"alias": "refused",
"name": "Pagamento não aprovado"
},
"created_at": {
"date": "2025-01-01 09:25:14.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 09:33:29.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"items": {
"data": [
{
"id": 777777,
"product_id": 111111,
"sku_id": 222222,
"quantity": 1,
"price": 20,
"gift": false,
"has_recomm": false,
"customizations": [],
"created_at": {
"date": "2025-01-01 09:25:14.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 09:25:14.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"sku": {
"data": {
"id": 222222,
"product_id": 111111,
"sku": "SKU123456",
"token": "sku-token-exemplo",
"title": "Produto Exemplo",
"availability": 0,
"availability_soldout": -1,
"days_availability_formated": "Imediata",
"price_cost": 17,
"price_sale": 8,
"price_discount": 20,
"width": 0,
"height": 0,
"length": 0,
"weight": 0,
"quantity_managed": false,
"variations": [],
"combinations": "222222",
"order": 0,
"total_in_stock": 0,
"total_orders": null,
"allow_sell_without_customization": false,
"image_reference_sku_id": null,
"purchase_url": "https://lojaexemplo.com.br/r/sku-token-exemplo",
"created_at": {
"date": "2025-01-01 09:24:15.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 09:24:48.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"customizations": { "data": [] }
}
}
}
]
}
}
}
}
}
Exemplo de payload retornados em
order.invoice.created e order.invoice.updated.{
"event": "order.invoice.created",
"time": "2025-01-01 10:00:00",
"merchant": {
"id": 123,
"alias": "lojaexemplo"
},
"resource": {
"id": 999999,
"merchant_id": 123,
"order_id": 888888,
"series": "ABC1234567890",
"number": "123456789",
"key": "00000000000000000000000000000000000000000000",
"date": {
"date": "2025-01-02 00:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"value": 199.90,
"products_value": 180.00,
"cpfop": null,
"url": "https://exemplo.com.br/nfe/visualizar/00000000000000",
"created_at": {
"date": "2025-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-01-01 10:00:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
}
}
}
Exemplo de payload retornados em
product.inventory.updated.{
"event": "product.inventory.updated",
"time": "2025-05-15 10:13:12",
"merchant": { "id": 0, "alias": "loja_anonima" },
"resource": {
"id": 0,
"stock_id": 0,
"quantity": 0,
"min_quantity": 1,
"created_at": {
"date": "2025-05-15 10:13:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2025-05-15 10:13:00.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"stock": {
"data": {
"id": 0,
"warehouse_id": null,
"priority": false,
"auto_refill": false,
"name": "Estoque Anônimo",
"delivery_days": 14,
"created_at": {
"date": "2022-03-25 15:42:29.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"updated_at": {
"date": "2022-03-25 15:42:29.000000",
"timezone_type": 3,
"timezone": "America/Sao_Paulo"
},
"warehouse": { "data": [] }
}
},
"spreadsheet": {
"data": {
"stock": "Estoque Anônimo",
"product": "Produto de Teste",
"sku": "XXXXXXX",
"quantity": 0,
"min_quantity": 1
}
}
}
}
⚠️ Sua aplicação deve responder em até 5 segundos com um status code do nível 2XX. Caso contrário, a Yampi abortará a requisição e marcará como uma falha. Após 30 falhas, o webhook será desativado automaticamente.
Segurança
A validação do webhook serve para verificar se realmente ele foi enviado pela Yampi, e é de extrema importância a sua utilização para que suas transações estejam seguras. Para fazer a validação, são necessárias duas informações de nosso webhook:- Valor do header
X-Yampi-Hmac-SHA256. Vamos chamar esse valor de “assinatura do webhook”; - Corpo da requisição (no mesmo formato mostrado acima). Com esses dois valores, basta realizar o base64 do algoritmo HMAC-SHA256 do corpo da requisição utilizando a chave secreta do Webhook e comparar com a assinatura do webhook. Se os valores forem iguais, excelente. Caso contrário, não fomos nós que enviamos essa requisição!
Exemplo de validação em PHP
function hmac_signature(array $body, $webHookSecret)
{
$payload = json_encode($body);
return base64_encode(hash_hmac('sha256', $payload, $webHookSecret, true));
}
// Calculando a assinatura
$body = [
'event' => 'order.created',
'time' => '2020-06-20 00:00:00',
'resource' => [
'id' => 1121333,
// Aqui vem todo o payload do resource.
],
];
$signature = hmac_signature($body, 'wh_FBmkbmkMSAKmkMBKmdsbUUHjnlmlm');
echo $signature; // Output: NzhjMmM3NzcwZDM5NmM1ZWYxNjhjMDI5NmVhYjgzOTFlNDNlNmU0OWU5ZWZhMTRiYTIyNTI0NzdhNTVhZTMxNQ
Importante: é esperado que o base64 seja calculado em cima do hmac em formato binário. No exemplo em PHP, é o terceiro argumento da função hash_hmac()