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.

​
Eventos disponíveis

Abaixo estão os eventos atualmente suportados. Você pode configurar webhooks para escutar um ou mais desses eventos:

EventoDescriçãoExemplos
order.createdPedido criadoVer payload
order.paidPedido aprovadoVer payload
order.status.updatedO status de um pedido foi atualizadoVer payload
order.invoice.createdNota fiscal de um pedido foi criadaVer payload
order.invoice.updatedNota fiscal de um pedido foi atualizadaVer payload
transaction.payment.refusedO pagamento de uma transação foi negadoVer payload
cart.reminderNotificação de carrinho abandonadoVer payload
customer.createdCliente criadoVer payload
customer.address.createdEndereço do cliente criadoVer payload
product.createdProduto criadoVer payload
product.updatedProduto atualizadoVer payload
product.deletedProduto excluídoVer payload
product.inventory.updatedEstoque de produto atualizadoVer payload
cashback.expiringUm Cashback está expirandoVer payload

​
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.

{
  "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"
        }
      ]
    }
  }
}

⚠️ 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()