Webhook

I webhook consentono a Cost+ di notificare il tuo server in tempo reale ogni volta che lo stato di un ordine cambia. Invece di interrogare l'API tramite polling, fornisci un URL e Cost+ invia una richiesta HTTP POST ogni volta che c'è un aggiornamento.

Come Funzionano i Webhook

Specifichi un webhook_url quando crei un ordine, o configuri un URL webhook predefinito a livello di progetto.
Quando lo stato dell'ordine cambia (es. da new a completed), Cost+ invia una richiesta POST al tuo URL webhook.
Il tuo server riceve il webhook, quindi chiama l'API Cost+ per recuperare i dettagli completi dell'ordine.
Aggiorni il tuo sistema in base allo stato dell'ordine verificato.

Non fidarti mai solo del payload del webhook per evadere un ordine. Verifica sempre lo stato dell'ordine effettuando una richiesta GET /v1/orders/{id}/ dopo aver ricevuto un webhook. Il webhook è un meccanismo di notifica, non una fonte di verità.

Payload del Webhook

Il corpo del webhook è un oggetto JSON contenente il tipo di evento e l'ID dell'ordine:

{
  "event": "status_changed",
  "order_id": "b9ae6...",
  "project_id": "proj_abc123"
}

Campo	Descrizione
`event`	Il tipo di evento. Attualmente `status_changed` per gli aggiornamenti degli ordini.
`order_id`	L'identificatore univoco dell'ordine il cui stato è cambiato.
`project_id`	Il progetto a cui appartiene l'ordine.

Impostare l'URL del Webhook

Puoi impostare l'URL del webhook in due modi:

Per Singolo Ordine

Includi il campo webhook_url quando crei un ordine:

{
  "currency": "EUR",
  "amount": 1295,
  "webhook_url": "https://www.example.com/webhook"
}

Predefinito del Progetto

Configura un URL webhook predefinito nella tua dashboard Cost+ nelle impostazioni del progetto. Questo URL verrà utilizzato per tutti gli ordini che non specificano il proprio webhook_url.

Anche se hai un URL predefinito a livello di progetto, puoi sovrascriverlo per singolo ordine includendo webhook_url nella richiesta di creazione dell'ordine.

Logica di Retry

Se il tuo server non risponde con un codice di stato 2xx, Cost+ ritenta la consegna del webhook:

Tentativi massimi: 10 tentativi
Intervallo tra tentativi: 2 minuti tra ogni tentativo
Timeout primo tentativo: 4 secondi
Timeout tentativi successivi: 10 secondi

Se tutti i 10 tentativi falliscono, il webhook viene contrassegnato come fallito. Puoi comunque recuperare lo stato dell'ordine in qualsiasi momento tramite polling dell'API.

Assicurati che il tuo endpoint webhook risponda rapidamente (entro 4 secondi per il primo tentativo). Esegui qualsiasi elaborazione di lunga durata in modo asincrono dopo aver restituito una risposta 200 OK.

Best Practice

Verifica sempre tramite API. Alla ricezione di un webhook, chiama GET /v1/orders/\{order_id\}/ per confermare lo stato attuale prima di intraprendere azioni come spedire merci o concedere accessi.
Restituisci 200 rapidamente. Conferma il webhook con una risposta 200 immediatamente ed elabora l'ordine in modo asincrono per evitare timeout.
Gestisci i duplicati. Il tuo endpoint webhook potrebbe ricevere lo stesso evento più di una volta. Assicurati che la tua logica di elaborazione sia idempotente.
Usa HTTPS. Utilizza sempre un URL HTTPS per il tuo endpoint webhook per garantire che il payload sia trasmesso in modo sicuro.
Registra i payload dei webhook. Archivia i dati dei webhook in arrivo per scopi di debug e audit.

Endpoint Correlati

Crea Ordine — imposta il webhook_url per singolo ordine
Aggiorna Ordine — aggiorna l'URL del webhook su un ordine esistente
Schemi degli Eventi Webhook — formato del payload per OrderStatusChangedEvent e TransactionStatusChangedEvent

On this page