Webhooks en API-sleutels in PortalX

Webhooks sturen realtime meldingen naar uw eigen systeem wanneer er iets gebeurt in QrX, zoals een betaling of een bezorging. Met API-sleutels kan uw systeem transacties aanmaken via de QrX API. De API-documentatie staat op qrx.eu/api.

API-sleutels

Elk verkoopkanaal heeft een eigen API-sleutel: Settings > Business > Merchant Channels, open het kanaal, tabblad Settings, API Key (recht Manage Channels). De sleutel wordt veilig opgeslagen en slechts één keer volledig getoond, wanneer u op Regenerate API Key (API-sleutel opnieuw genereren) klikt. Kopieer deze direct. Opnieuw genereren stopt elke integratie die nog de oude sleutel gebruikt.

Onder de API-sleutel vindt u het blok API-toegang. Een sleutel begint met Volledige toegang. Zet Deze sleutel beperken aan om de sleutel te beperken tot de onderdelen van de API die u aanvinkt, bijvoorbeeld alleen voorraad lezen. Zie "Een API-sleutel beperken (API-toegang)".

Een webhook aanmaken

Ga naar Settings > Advanced > Webhooks.

Voer een naam en de URL van uw endpoint (https) in.
Kies de API-versie en optioneel één kanaal (of All Channels).
Klik op de gebeurtenissen die u wilt ontvangen. Gebruik Customize payload om de velden te kiezen die voor een gebeurtenis worden verstuurd.
Laat Active aan staan. Zolang een webhook is gepauzeerd, worden gebeurtenissen overgeslagen, niet in de wachtrij gezet.

Gebeurtenissen

Transactie: aangemaakt, betaald, verlopen, terugbetaald, geannuleerd en status gewijzigd.
Zending: aangemaakt, verzonden, bezorgd en label aangemaakt.
Bestelling: geannuleerd. Betaling: uitbetaling verwerkt. Bezorging: bevestigd.
Retourgebeurtenissen: aangevraagd, informatie vereist, goedgekeurd, afgewezen, label uitgegeven, onderweg, ontvangen, geïnspecteerd, afgerond, terugbetaald, geannuleerd en meer.
Fulfilment (QrX WMS): picklist/created, picklist/completed, fulfilment/picked, fulfilment/packed en fulfilment/exception. Zie "Paktafel en picklijsten".
Voorraad (QrX WMS magazijnvoorraad): stock/adjusted (de voorraad van een artikel is in een magazijn gewijzigd) en stock/low (een artikel is gedaald tot zijn waarschuwingsniveau voor lage voorraad). Ze gaan naar elke actieve webhook die ze heeft aangevinkt, ook naar een webhook voor één kanaal. Zie "Voorraad- en magazijnwebhooks".

Beveiliging

Elke bezorging is ondertekend. Controleer de header X-QrX-Signature met het ondertekeningsgeheim van uw webhook; X-QrX-Event en X-QrX-Delivery-Id identificeren de gebeurtenis en de bezorging. Gebruik Rotate om het geheim te wijzigen: dit geldt direct voor alle volgende bezorgingen, dus werk eerst uw endpoint bij.

Storingen en testen

Failure Notifications (storingsmeldingen): kies teamleden die een e-mail krijgen. Na 6 uur aanhoudende storingen wordt een waarschuwing verstuurd, en na 24 uur wordt de webhook automatisch uitgeschakeld. Herstel uw endpoint en zet de webhook weer aan in de editor.
Send Test verstuurt een voorbeeldgebeurtenis, ook als de webhook is uitgeschakeld.
Delivery Logs (bezorglogboeken): zoek op transactie-ID, order-ID of gebeurtenis. Statussen: Queued, Delivering, Delivered, Retrying, Failed en Cancelled. Open een bezorging om het request en de response te zien, of gebruik Redeliver (opnieuw bezorgen) of annuleer deze.
De editor toont het aantal geslaagde en mislukte bezorgingen van de afgelopen 24 uur. In de gevarenzone kunt u de geschiedenis wissen of de webhook verwijderen.

Apps koppelen (OAuth)

Sommige apps, zoals de QrX Shopify-app, koppelen via een toestemmingsscherm ("Connect QrX"). U kiest één kanaal en klikt op Allow (toestaan). De app kan dan transacties met betaling bij levering en verzendlabels aanmaken en de betaal- en zendingsstatus lezen, alleen voor dat kanaal. De app kan geen facturering, gebruikers of andere kanalen wijzigen.

Wanneer neemt u contact op met ons supportteam

Neem contact op met QrX wanneer bezorgingen mislukken hoewel uw endpoint 2xx teruggeeft, wanneer handtekeningen niet te verifiëren zijn met het huidige geheim, of wanneer u een gebeurtenis nodig hebt die niet in de lijst staat. Vermeld de naam van de webhook en een bezorg-ID.