Webhooks

Webhooks stellen Cost+ in staat om uw server in real-time te informeren wanneer de status van een bestelling verandert. In plaats van de API te pollen, geeft u een URL op en stuurt Cost+ een HTTP POST-verzoek ernaartoe wanneer er een update is.

Hoe webhooks werken

U specificeert een webhook_url bij het aanmaken van een bestelling, of configureert een standaard webhook-URL op projectniveau.
Wanneer de bestellingsstatus verandert (bijv. van new naar completed), stuurt Cost+ een POST-verzoek naar uw webhook-URL.
Uw server ontvangt de webhook en roept vervolgens de Cost+ API aan om de volledige bestellingsdetails op te halen.
U werkt uw systeem bij op basis van de geverifieerde bestellingsstatus.

Vertrouw nooit alleen op de webhook-payload om een bestelling te verwerken. Verifieer altijd de bestellingsstatus door een GET /v1/orders/{id}/-verzoek te doen na ontvangst van een webhook. De webhook is een meldingsmechanisme, geen bron van waarheid.

Webhook-payload

De webhook-body is een JSON-object met het gebeurtenistype en het bestelling-ID:

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

Veld	Beschrijving
`event`	Het type gebeurtenis. Momenteel `status_changed` voor bestellingsupdates.
`order_id`	De unieke identificatie van de bestelling waarvan de status is gewijzigd.
`project_id`	Het project waartoe de bestelling behoort.

De webhook-URL instellen

U kunt de webhook-URL op twee manieren instellen:

Per bestelling

Neem het veld webhook_url op bij het aanmaken van een bestelling:

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

Projectstandaard

Configureer een standaard webhook-URL in uw Cost+ dashboard onder projectinstellingen. Deze URL wordt gebruikt voor alle bestellingen die geen eigen webhook_url opgeven.

Zelfs als u een standaard op projectniveau heeft, kunt u deze per bestelling overschrijven door webhook_url op te nemen in het verzoek voor het aanmaken van de bestelling.

Herhaalpogingen

Als uw server niet reageert met een 2xx-statuscode, herhaalt Cost+ de webhooklevering:

Maximaal aantal herhaalpogingen: 10 pogingen
Interval tussen herhaalpogingen: 2 minuten tussen elke poging
Time-out eerste poging: 4 seconden
Time-out volgende pogingen: 10 seconden

Als alle 10 herhaalpogingen mislukken, wordt de webhook als mislukt gemarkeerd. U kunt de bestellingsstatus op elk moment ophalen door de API te pollen.

Zorg ervoor dat uw webhook-eindpunt snel reageert (binnen 4 seconden voor de eerste poging). Voer langdurige verwerking asynchroon uit nadat u een 200 OK-respons heeft geretourneerd.

Best practices

Verifieer altijd via de API. Roep na ontvangst van een webhook GET /v1/orders/\{order_id\}/ aan om de huidige status te bevestigen voordat u actie onderneemt zoals het verzenden van goederen of het verlenen van toegang.
Retourneer snel 200. Bevestig de webhook onmiddellijk met een 200-respons en verwerk de bestelling asynchroon om time-outs te voorkomen.
Behandel duplicaten. Uw webhook-eindpunt kan dezelfde gebeurtenis meer dan eens ontvangen. Zorg ervoor dat uw verwerkingslogica idempotent is.
Gebruik HTTPS. Gebruik altijd een HTTPS-URL voor uw webhook-eindpunt om ervoor te zorgen dat de payload veilig wordt verzonden.
Log webhook-payloads. Sla inkomende webhookdata op voor foutopsporing en auditdoeleinden.

Gerelateerde eindpunten

Bestelling aanmaken — de webhook_url per bestelling instellen
Bestelling bijwerken — de webhook-URL van een bestaande bestelling bijwerken
Webhook-gebeurtenisschema's — payloadformaat voor OrderStatusChangedEvent en TransactionStatusChangedEvent

On this page