Naar hoofdinhoud gaan
Met webhooks kan AgencyHandy gegevens naar uw externe systemen sturen op het moment dat er iets wijzigt — geen polling vereist. Wanneer een geconfigureerde gebeurtenis plaatsvindt (bijvoorbeeld een bestelling wordt bijgewerkt of een ticket wordt aangemaakt), stuurt AgencyHandy een HTTP POST-verzoek met een JSON-payload naar de eindpunt-URL die u opgeeft. Dit maakt het eenvoudig om externe tools zoals CRM’s, factureringssystemen of aangepaste dashboards gesynchroniseerd te houden met uw AgencyHandy-werkruimte in real time.
Business Pro-plan werkruimtes ondersteunen tot 30.000 webhookgebeurtenissen per factureringsperiode. Controleer uw planbeperkingen voordat u automatiseringen met hoog volume instelt.

​
Ondersteunde gebeurtenissen

U kunt een webhook abonneren op elke combinatie van de volgende gebeurtenissen:
CategorieGebeurtenissen
DienstAangemaakt, Bijgewerkt, Verwijderd
BestellingAangemaakt, Bijgewerkt, Verwijderd
TaakAangemaakt, Toegewezen, Voltooid, Bijgewerkt
FactuurStatus gewijzigd
Klant / GebruikerNieuwe klant toegevoegd, Klant/gebruiker verwijderd
VoorstelVerstuurd, Ontvangen, Geaccepteerd, Afgewezen
TicketAangemaakt, Toegewezen, Status gewijzigd
BetalingOntvangen, Mislukt
ServicepakketAangemaakt, Bijgewerkt, Verwijderd

​
Een webhook aanmaken

1

Navigeer naar Webhookbeheer

Ga in de linker zijbalk naar Integraties → Webhookbeheer.
2

Authenticeer uw token

Klik op de knop Beheer om uw webhooktoken te authenticeren. Dit token wordt gebruikt om uitgaande payloads te ondertekenen zodat u kunt verifiëren dat ze afkomstig zijn van AgencyHandy.
3

Maak een nieuwe webhook aan

Klik op Nieuwe webhook aanmaken om het webhookconfiguratie­formulier te openen.
4

Voer de eindpunt-URL in

Voer in het veld Eindpunt-URL de URL in van het externe systeem dat de webhookgegevens moet ontvangen. Dit moet een openbaar toegankelijk POST-eindpunt zijn.
5

Selecteer het inhoudstype

Kies JSON als inhoudstype. AgencyHandy verstuurt alle webhookpayloads als application/json.
6

Selecteer webhookgebeurtenissen

Kies elke gebeurtenis die deze webhook moet activeren. U kunt gebeurtenissen uit meerdere categorieën selecteren — zo kunnen bijvoorbeeld Bestelling: Aangemaakt en Factuur: Status gewijzigd beide naar hetzelfde eindpunt verwijzen.
7

Activeer de webhook

Schakel de radioknop Actief in. Wanneer actief, levert AgencyHandy payloads voor alle geselecteerde gebeurtenissen in real time aan uw eindpunt.
8

Sla de configuratie op

Bekijk uw instellingen en klik op Opslaan. De webhook verschijnt in de lijst en begint onmiddellijk met het leveren van gebeurtenissen.

​
Een webhook testen

Stuur na het aanmaken van een webhook een testpayload om te bevestigen dat uw eindpunt bereikbaar is en gegevens correct verwerkt.
1

Open de webhook

Klik in de lijst Webhookbeheer op de webhook die u wilt testen.
2

Klik op Testgebeurtenis

Klik op de knop Testgebeurtenis op de detailpagina van de webhook.
3

Selecteer een testgebeurtenis

Kies een voorbeeldgebeurtenis uit de lijst met gebeurtenissen die op deze webhook zijn geconfigureerd (bijv. Bestelling: Aangemaakt).
4

Stuur de testpayload

Klik op Verzenden. AgencyHandy plaatst een voorbeeldpayload naar uw eindpunt-URL.
5

Verifieer het resultaat

Controleer uw externe systeem om te bevestigen dat de testpayload is aangekomen en correct is verwerkt. Klik in AgencyHandy op de webhook om de geschiedenis te bekijken — u kunt het volledige verzoek, het antwoord van uw eindpunt en eventuele eerdere gebeurtenissen opnieuw bezorgen.
Gebruik een tool zoals Webhook.site of RequestBin als tijdelijk eindpunt tijdens de instelling om de exacte payload-structuur te inspecteren voordat u uw echte systeem aansluit.

​
Webhookpayloads authenticeren

Elk uitgaand webhookverzoek van AgencyHandy bevat een handtekeningheader die uw eindpunt kan gebruiken om te verifiëren dat de payload authentiek is en niet is gemanipuleerd.

​
Handtekeningheader

x-ah-sig: <signature>
AgencyHandy voegt deze header toe aan elk webhookverzoek. Extraheer de waarde uit inkomende verzoeken en geef deze door aan het verificatie-eindpunt.

​
Een webhookhandtekening verifiëren

Stuur het volgende verzoek om te bevestigen dat een payload authentiek is: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
vereist
Het ID van de webhook die de gebeurtenis heeft ontvangen. Dit is te vinden op de detailpagina van de webhook in AgencyHandy.
​
signature
string
vereist
De waarde van de x-ah-sig-header uit het inkomende webhookverzoek.
​
secret
string
vereist
Het webhookgeheim dat wordt weergegeven op de detailpagina van de webhook in AgencyHandy.
​
payload
object
vereist
De onbewerkte JSON-body ontvangen van het webhookverzoek van AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Antwoorden
​
verification_status
string
SUCCESS wanneer de handtekening geldig is. FAILED wanneer verificatie mislukt (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Houd uw webhookgeheim vertrouwelijk. Roteer het periodiek en werk uw verificatielogica onmiddellijk bij na rotatie. Stel het nooit bloot in client-side code of openbare repositories.

​
Belangrijke opmerkingen

  • Uw eindpunt-URL moet een openbaar toegankelijke HTTPS POST-URL zijn.
  • Als uw eindpunt tijdelijk niet beschikbaar is, controleer dan het geschiedenispaneel van de webhook in AgencyHandy — u kunt elke eerdere gebeurtenis direct van daaruit opnieuw bezorgen.
  • Bewaak regelmatig webhookactiviteit om mislukte bezorgingen of ongeautoriseerde toegangspogingen te detecteren.
  • Webhooks die herhaaldelijk mislukken kunnen door AgencyHandy worden gepauzeerd — bekijk bezorgingslogs om problemen vroegtijdig te ondervangen.