> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Visão Geral
> Como funcionam os webhooks na Yampi e exemplos de payloads.
Webhooks permitem que a plataforma envie uma requisição `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](/api-reference/webhooks/listar-webhooks).
A criação dos webhooks é restrita ao limite definido ao plano da sua loja, acesse a [página de planos](https://www.yampi.com.br/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](#pedidos) |
| order.paid | Pedido aprovado | [Ver payload](#pedidos) |
| order.status.updated | O status de um pedido foi atualizado | [Ver payload](#pedidos) |
| order.invoice.created | Nota fiscal de um pedido foi criada | [Ver payload](#notas-fiscais) |
| order.invoice.updated | Nota fiscal de um pedido foi atualizada | [Ver payload](#notas-fiscais) |
| transaction.payment.refused | O pagamento de uma transação foi negado | [Ver payload](#transacoes) |
| cart.reminder | Notificação de carrinho abandonado | [Ver payload](#carrinho-abandonado) |
| customer.created | Cliente criado | [Ver payload](#clientes) |
| customer.address.created | Endereço do cliente criado | [Ver payload](#enderecos-de-clientes) |
| product.created | Produto criado | [Ver payload](#produtos) |
| product.updated | Produto atualizado | [Ver payload](#produtos) |
| product.deleted | Produto excluído | [Ver payload](#produtos) |
| product.inventory.updated | Estoque de produto atualizado | [Ver payload](#estoque) |
| cashback.expiring | Um Cashback está expirando | [Ver payload](#cashback) |
## Exemplos de payloads de Webhook
Aqui centralizaremos todos os payloads retornados por cada webhook.
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.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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`.
```json theme={"system"}
{
"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
```php theme={"system"}
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()