Webhooks: zo werkt dit scherm
Webhooks sturen QrX-events naar je eigen systeem op het moment dat ze gebeuren: een betaling, een zending, een retour, een picklijst en meer. QrX stuurt een ondertekend bericht naar een webadres (URL) dat jij kiest. Deze gids legt de lijst met webhooks en elk onderdeel van de webhook-editor uit.
Wat je op dit scherm ziet
Toevoegen (rechtsboven): maak een nieuwe webhook aan.
Overzichtskaarten: Webhooks (alle geladen webhooks), Actief, Inactief en Aandacht nodig (webhooks die mislukken of automatisch zijn uitgeschakeld). De aantallen gaan over de webhooks die in de lijst zijn geladen.
Zoek webhooks...: vind een webhook op naam of URL.
Alle, Actief, Inactief: toon alleen die webhooks.
Vernieuwen (de ronde pijl): laadt de lijst opnieuw.
De webhooklijst: laadt vanzelf meer rijen terwijl je scrolt. Op een klein scherm scrol je de tabel opzij om alle kolommen en acties te zien.
De kolommen
Naam: de naam die je de webhook gaf, de URL en de API-versie. Klik op de naam om de webhook te openen. Klik op de kolomtitel om op naam te sorteren.
Kanaal: Alle Kanalen, of het ene verkoopkanaal waartoe deze webhook beperkt is.
Evenementen: op hoeveel events de webhook luistert, met de eerste twee namen.
Status: Actief, Uitgeschakeld (jij hebt hem uitgezet), Verslechterd (leveringen mislukken op dit moment), Automatisch uitgeschakeld (QrX heeft hem uitgezet na 24 uur fouten) of Foutief (meerdere leveringen achter elkaar zijn mislukt).
Afgeleverd · 24 uur en Mislukt · 24 uur: geslaagde en mislukte leveringen in de laatste 24 uur.
Bijgewerkt: wanneer de webhook voor het laatst is gewijzigd, en het tijdstip van de laatste levering. Klik op de kolomtitel om op datum te sorteren.
Acties per rij
Aflevering opnieuw inschakelen (aan/uit-icoon, alleen bij inactieve webhooks): zet de webhook weer aan. Leveringen gaan meteen weer door.
Bewerk (potlood): opent de webhook.
Kopiëren: opent een nieuwe webhook met dezelfde naam (plus "copy"), events, kanaal, API-versie, payloadvelden en ontvangers van meldingen. De URL blijft leeg, zodat je het nieuwe adres invult. Er wordt pas iets aangemaakt als je opslaat.
Verwijderen (prullenbak): vraagt je om te bevestigen en verwijdert dan de webhook. Leveringen stoppen en dit kan niet ongedaan worden gemaakt.
Een webhook aanmaken of bewerken
Klik op Toevoegen (of op een webhook in de lijst). Het menu links toont ook hoeveel events aan staan, bijvoorbeeld 3/33. De editor heeft een balk bovenaan en een menu links (Eindpunt, Events, Beveiliging, Meldingen, Bezorgingen, Gevarenzone) om naar elk onderdeel te springen. Beveiliging, Bezorgingen en Gevarenzone verschijnen zodra de webhook is opgeslagen.
Niet-opgeslagen wijzigingen of Alle wijzigingen opgeslagen: laat zien of je nog moet opslaan.
Opslaan: slaat de webhook op. Je kunt ook Ctrl+S indrukken (Cmd+S op een Mac).
Annuleren: terug naar de lijst zonder op te slaan.
Test Versturen (alleen opgeslagen webhooks): stuurt een testevent naar je URL. Luistert de webhook naar meer dan één event, kies dan eerst het testevent in het veld ernaast. Het resultaat verschijnt na een paar seconden onder Bezorgingen. Testevents worden ook verstuurd als de webhook uitstaat, zodat je je eindpunt kunt controleren voordat je hem weer aanzet.
Kopiëren (alleen opgeslagen webhooks): start een nieuwe webhook vanuit deze, net als Kopiëren in de lijst.
Onder de balk zie je de URL (klik erop om te kopiëren), de status, het kanaal, de API-versie, het aantal events en de datum waarop hij is aangemaakt. Bij een opgeslagen webhook zie je ook de gezondheid van de leveringen: Succespercentage, Mediane latentie (hoe snel je eindpunt antwoordt), Bezorgingen · 24u en Mislukt · 24 uur (met hoeveel er wachten op een nieuwe poging).
Als de webhook mislukt of uitgeschakeld is, legt een gekleurde banner uit waarom. Bij een uitgeschakelde webhook klik je op Opnieuw inschakelen in de banner om de leveringen weer aan te zetten.
Eindpunt
Naam (verplicht): een naam die je herkent, bijvoorbeeld "Mijn koppeling".
Eindpunt-URL (verplicht): het adres dat de berichten ontvangt. Het moet beginnen met https://. Als QrX met succes naar deze URL heeft geleverd, zie je Geverifieerd via bezorging.
Kanaal: laat Alle Kanalen staan, of beperk de webhook tot één verkoopkanaal.
API Versie: het berichtformaat dat je eindpunt verwacht. De nieuwste is gemarkeerd met Nieuwste.
Actief: zet uit om leveringen te pauzeren zonder de webhook te verwijderen. Events die gebeuren terwijl hij gepauzeerd is, worden overgeslagen en niet later verstuurd.
Events
Kies welke events een bericht sturen. Events zijn per onderwerp gegroepeerd, en de groepsnamen staan in je eigen taal: Transactie, Zending, Order, Betaling, Bezorging, Retour, Fulfilment, Inbound en Voorraad, plus de picklijst-events.
Klik op een event om het aan of uit te zetten. Gebruik Alles selecteren of Alles deselecteren bij een groep, en de pijl om een groep open of dicht te klappen.
Events filteren…: typ een deel van een eventnaam om het te vinden.
De teller laat zien hoeveel van de beschikbare events aan staan, bijvoorbeeld "3 / 33 events geabonneerd".
Payload aanpassen (het schuifregelaar-icoon naast een event dat aan staat): kies welke velden het bericht bevat. Je ziet elk veld met zijn type, welke velden Verplicht zijn (altijd meegestuurd), een Voorbeeld Payload die je kunt kopiëren, Alles selecteren en Standaard herstellen. Je keuze geldt voor elk event van dezelfde groep. Klik op Klaar om te sluiten; de keuze wordt bewaard als je de webhook opslaat.
De groep Voorraad heeft twee events: stock/adjusted (de voorraad van een artikel is in een magazijn veranderd) en stock/low (een artikel is naar zijn waarschuwingsniveau voor lage voorraad of lager gezakt; één keer per daling verstuurd). Heeft een fulfilmentpartner jouw voorraad, dan ontvang je deze events voor je eigen artikelen, zonder locaties.
Magazijndocumenten hebben hun eigen groepen: Ontvangsten (receipt/created, receipt/line_received, receipt/completed), Inkooporders (purchase_order/created, purchase_order/sent, purchase_order/received, purchase_order/closed), Tellingen (count/completed, count/approved), Containers (container/created, container/moved, container/emptied), Teamtaken (task/created, task/completed) en Overboekingen (transfer/sent, transfer/received, transfer/completed, transfer/cancelled: voorraad verplaatst tussen je eigen magazijnen; transfer/received wordt bij elke ontvangst verstuurd en bevat de ontvangen regels, en elk overboekingsevent bevat de vervoerder en de tracking). Fulfilment heeft ook picklist/assigned, picklist/cancelled, picklist/batch_created en fulfilment/snoozed (een order is gesnoozed of de snooze is opgeheven). Deze events en de Inbound-events horen bij geen enkel verkoopkanaal: elke webhook van je account die ze selecteert ontvangt ze, ook een webhook die beperkt is tot één kanaal. Elk nieuw event heeft een voorbeeldpayload; geen ervan bevat prijzen of kosten.
fulfilment/picked wordt één keer per bestelling verstuurd, zodra het picken van die bestelling op de telefoon is afgerond.
De voorbeeld-payload van de voorraad-, picklijst- en fulfilment-events toont een volledig voorbeeld van het bericht, zodat je elk veld ziet voordat je je koppeling bouwt.
Beveiliging
Ondertekeningsgeheim: QrX ondertekent elk bericht met dit geheim. Gebruik het oog-icoon om het te tonen of te verbergen en het kopieer-icoon om het te kopiëren.
Roteren…: maakt een nieuw geheim. Alle volgende berichten worden meteen met het nieuwe ondertekend, dus werk het geheim eerst bij in je systeem.
Codevoorbeelden (Node, C#, Python, PHP, cURL): laten zien hoe je systeem de handtekening controleert.
Ondertekende request-headers: elk bericht bevat X-QrX-Signature (de handtekening van de berichttekst), X-QrX-Event (de naam van het event) en X-QrX-Delivery-Id (een unieke id van de levering).
Meldingen (Foutmeldingen)
Klik op Ontvanger toevoegen en kies collega's uit je team. Ze krijgen een e-mail als deze webhook blijft mislukken: een waarschuwing na 6 uur fouten achter elkaar, en een bericht als QrX de webhook na 24 uur uitschakelt. Klik op het kruisje bij een naam om die te verwijderen. Sla de webhook op om de wijziging te bewaren.
Bezorgingen (Webhook logs)
Elk bericht dat QrX naar deze webhook stuurde, nieuwste eerst. Nieuwe leveringen verschijnen vanzelf zolang het label Live zichtbaar is.
Zoeken: vind leveringen op transactie-ID, bestelnummer of event.
Alle, Bezorgd, Mislukt, Opnieuw proberen: toon alleen die leveringen.
24h, 7d, 30d: de periode voor de grafiek en de gezondheidskaarten bovenaan.
Vernieuwen: laadt de leveringen opnieuw.
De kolommen tonen de Status, het Evenement, de Transactie-ID, de HTTP-status waarmee je eindpunt antwoordde, de Duur, het nummer van de Poging en wanneer het Bezorgd is. Is een bericht meer dan eens geprobeerd, klik dan op de pijl aan het begin van de rij om elke poging te zien.
Bekijk de bezorgdetails (oog-icoon): toont het volledige verzoek en antwoord, met een eventuele fout.
Opnieuw bezorgen: stuurt hetzelfde bericht nog een keer.
Bezorging annuleren (alleen zolang een levering in de wachtrij staat of opnieuw wordt geprobeerd): stopt de resterende pogingen.
Gevarenzone
Bezorggeschiedenis wissen: verwijdert de opgeslagen verzoeken en antwoorden van deze webhook voorgoed. De webhook blijft werken.
Webhook Verwijderen: stopt alle leveringen en verwijdert de webhook voorgoed.
Bij beide moet je eerst bevestigen en ze kunnen niet ongedaan worden gemaakt.
Je eerste webhook instellen
Klik op Toevoegen.
Vul een Naam en je Eindpunt-URL (https) in.
Kies een Kanaal als de webhook maar voor één kanaal is.
Zet de Events aan die je nodig hebt.
Voeg eventueel collega's toe onder Meldingen.
Klik op Opslaan. Het onderdeel Beveiliging toont nu je ondertekeningsgeheim: voeg het toe aan je systeem om de handtekening te controleren.
Klik op Test Versturen en bekijk het resultaat onder Bezorgingen.
Tips en veelgestelde vragen
"Naam is verplicht", "URL is verplicht", "Selecteer minstens één evenement": vul het ontbrekende deel in en sla opnieuw op.
Iemand anders wijzigde de webhook tegelijk: QrX toont een bericht en laat je de nieuwste versie opnieuw laden.
Mijn webhook staat op Automatisch uitgeschakeld: je eindpunt faalde 24 uur achter elkaar. Herstel je eindpunt, controleer het met Test Versturen en klik dan op Opnieuw inschakelen. Events uit de tijd dat hij uit stond, worden daarna niet automatisch verstuurd; gebruik Opnieuw bezorgen op een levering als je die nog nodig hebt.
Hoe weet ik dat een bericht echt van QrX komt? Bereken de HMAC-SHA256 van de ruwe berichttekst met je ondertekeningsgeheim en vergelijk die met de header X-QrX-Signature. Het onderdeel Beveiliging heeft kant-en-klare voorbeelden.
Hulp nodig? Klik op Chat onderaan het Helpcentrum.