Webhook
Beta · Q3
Evento order.created — Notifiche push
Quando nasce un ordine, te lo inviamo subito sul tuo endpoint con firma HMAC.
HTTPS POST
Firma HMAC-SHA256
Retry con backoff
Timeout 10s
Quickstart
3 passi e ricevi gli ordini in push.
1) Configura
URL
https://TUO-DOMINIO.it/webhooks/vorreiMetodo
POSTSecret
WEBHOOK_SECRET visibile nel pannelloEventi
order.createdProduzione in Q3 (beta controllata). In sandbox non puoi ancora provare l’invio.
2) Verifica firma
<?php
// Receiver minimale (PHP 7.4)
$secret = getenv('VORREI_WEBHOOK_SECRET'); // o da config
$body = file_get_contents('php://input');
$sig = isset($_SERVER['HTTP_X_VORREI_SIGNATURE']) ? $_SERVER['HTTP_X_VORREI_SIGNATURE'] : '';
list($algo, $hash) = explode('=', $sig, 2); // es. sha256=abcdef...
$valid = hash_equals(hash_hmac('sha256', $body, $secret), $hash);
if (!$valid) { http_response_code(400); exit('invalid signature'); }
// TODO: processa $body (JSON) in modo idempotente usando X-Vorrei-Delivery
http_response_code(200); echo 'ok';
Header inviati: X-Vorrei-Event, X-Vorrei-Delivery, X-Vorrei-Signature, X-Vorrei-Timestamp.
3) Test dalla Sandbox
curl -s -X POST "https://sandbox.vorreimenu.it/tools/send_webhook.php" \
-H "Authorization: Bearer <LA_TUA_CHIAVE_SANDBOX>" \
-H "Content-Type: application/json" \
-d '{
"event": "order.created",
"target_url": "https://TUO-DOMINIO.it/webhooks/vorrei",
"sample": true
}'
La Sandbox genera un payload di esempio, firma con il tuo WEBHOOK_SECRET e lo spedisce al tuo endpoint.
Schema payload (V2 essenziale)
Stesso modello “da scontrino” delle API ordini.
Esempio JSON
{
"version": "v2",
"event": "order.created",
"delivery_id": "whk_9d847c1f",
"created_at": "2025-10-31T10:22:45Z",
"ordine": {
"ordine_id": "409",
"numero_ordine": "409",
"data": "2025-10-31",
"ora": "10:20",
"canale": "consegna",
"posizione_servizio": "",
"km": 201,
"articoli": [
{ "titolo": "3333", "qta": 1, "prezzo_unitario": 2.00, "totale": 2.00, "varianti": [], "note": "" }
],
"totale": 22.00,
"pagamento": "Alla consegna",
"note_preparazione": "",
"note_consegna": ""
},
"cliente": {
"nome": "fabio pucci",
"email": "andromeda78ita@gmail.com",
"telefono": "+39 3513048018",
"indirizzo": "Via dei Cimatori 80",
"citta": "Roma",
"cap": "00186",
"provincia": "RM",
"presso": "nomesocieta",
"coordinate_gps": ""
}
}
Altri campi superflui/tecnici non vengono inclusi: privacy by design.
Header & sicurezza
- X-Vorrei-Event — es.
order.created - X-Vorrei-Delivery — id univoco consegna
- X-Vorrei-Timestamp — epoch in secondi
- X-Vorrei-Signature —
sha256=<HMAC_HEX>su raw body
Verifica: calcola
hash_hmac('sha256', body, WEBHOOK_SECRET) e confronta con la firma.
Consegna
- Timeout endpoint: 10s
- Ack valido: qualsiasi 2xx con body opzionale
- Content-Type inviato:
application/json - Idempotenza: usa X-Vorrei-Delivery per evitare doppi insert
Retry (backoff)
In caso di errore o timeout, riproviamo fino a 24h.
- 1m → 5m → 15m → 1h → 3h → 6h → 24h (stop)
- Se il tuo endpoint torna 410, consideriamo il webhook disattivato.
Esempi pronti
Snippet minimi per partire subito.
PHP — receiver completo
<?php
$secret = 'WEBHOOK_SECRET';
$body = file_get_contents('php://input');
$hdrSig = isset($_SERVER['HTTP_X_VORREI_SIGNATURE']) ? $_SERVER['HTTP_X_VORREI_SIGNATURE'] : '';
$delivery = isset($_SERVER['HTTP_X_VORREI_DELIVERY']) ? $_SERVER['HTTP_X_VORREI_DELIVERY'] : '';
list($algo, $hash) = explode('=', $hdrSig, 2);
$calc = hash_hmac('sha256', $body, $secret);
if (!hash_equals($calc, $hash)) { http_response_code(400); exit('bad signature'); }
$payload = json_decode($body, true);
// TODO: controlla se $delivery già processato -> se sì, return 200
// TODO: salva ordine / emetti scontrino
http_response_code(200); echo 'ok';
cURL — simulazione locale
# Simula un invio verso il tuo endpoint locale
BODY='{"version":"v2","event":"order.created","ordine":{"ordine_id":"1","articoli":[{"titolo":"Pizza","qta":1,"prezzo_unitario":8,"totale":8}],"totale":8,"pagamento":"contanti"},"cliente":{"nome":"Mario"}}'
SIG=$(php -r 'echo "sha256=".hash_hmac("sha256", $argv[1], $argv[2]);' "$BODY" "WEBHOOK_SECRET")
curl -s -X POST https://TUO-DOMINIO.it/webhooks/vorrei \
-H "Content-Type: application/json" \
-H "X-Vorrei-Event: order.created" \
-H "X-Vorrei-Delivery: whk_test_123" \
-H "X-Vorrei-Timestamp: '$(date +%s)'" \
-H "X-Vorrei-Signature: $SIG" \
-d "$BODY"
Apri la Sandbox
La disponibilità generale è prevista nel Q3. Durante la beta, l’attivazione è su richiesta per gli sviluppatori che vogliono farsi trovare pronti o hanno progetti da integrare.