# Webhooks instellen en gebruiken in Google Workspace

Met **webhooks in Google Workspace** krijg je realtime meldingen zodra er iets verandert, zonder steeds zelf te hoeven controleren. In dit artikel leer je hoe push-notificaties werken, hoe je een ontvanger opzet en hoe je webhooks veilig en betrouwbaar inzet.

[[TOC]]

## Wat is een webhook en waarom gebruik je het

Een webhook draait het normale aanvraagmodel om. Normaal vraagt jouw applicatie regelmatig aan een API of er iets nieuws is, wat pollen heet. Dat is inefficiënt: je doet veel aanvragen die niets opleveren. Met een webhook stuurt Google Workspace juist een bericht naar jou zodra er echt iets gebeurt.

Dit levert twee voordelen op. Je reageert direct in plaats van met vertraging, en je verbruikt veel minder API-aanvragen. Voor tijdkritische processen zoals een binnenkomend bestand of een nieuwe afspraak is dit de juiste aanpak.

:::info title="Push-notificaties in de Workspace-API's"
Google noemt webhooks meestal push-notificaties of watch-aanvragen. De Drive API en Calendar API ondersteunen dit via een directe HTTPS-URL. De Gmail API werkt anders: die levert meldingen via Cloud Pub/Sub. Je registreert telkens een kanaal en Google stuurt daar de meldingen naartoe.
:::

## Een webhook-ontvanger opzetten

Om webhooks te ontvangen heb je een publiek bereikbare URL nodig die HTTPS gebruikt met een geldig certificaat. Self-signed of ingetrokken certificaten worden door Google geweigerd. Dit endpoint ontvangt de meldingen en verwerkt ze. Tijdens ontwikkeling kun je tools gebruiken die een lokale server tijdelijk publiek maken met een geldig certificaat.

:::howto title="Een webhook registreren voor Drive-wijzigingen"
1. Zet een HTTPS-endpoint op met een geldig certificaat dat POST-aanvragen kan ontvangen en verwerken.
2. Bedenk een uniek kanaal-`token` dat je meegeeft, zodat je later kunt controleren dat een melding echt bij jouw kanaal hoort.
3. Roep de `watch`-methode van de Drive API aan met je endpoint-URL als `address` en je `token`.
4. Sla het kanaal-ID en de resource-ID op die je terugkrijgt, want die heb je nodig om het kanaal later te stoppen.
5. Verwerk inkomende meldingen en haal de daadwerkelijke wijziging op via een vervolgaanroep, want de melding zelf bevat geen bestandsinhoud.
6. Maak op tijd een nieuw kanaal aan voordat het oude verloopt, want kanalen hebben een beperkte levensduur en vernieuwen niet automatisch.
:::

:::danger
Vertrouw nooit blind op de inhoud van een binnenkomende webhook. Controleer altijd of de melding echt van Google komt door het kanaal-ID en het `X-Goog-Channel-Token` te valideren tegen de waarde die je zelf hebt ingesteld. Een onbeschermd endpoint kan door kwaadwillenden worden misbruikt met valse meldingen.
:::

## Levensduur van kanalen

Webhook-kanalen verlopen automatisch en vernieuwen niet vanzelf. De maximale levensduur verschilt per resource:

| Resource | Maximale levensduur | Standaard |
| --- | --- | --- |
| Drive `files` | 1 dag | 1 uur |
| Drive `changes` | 1 week | 1 uur |
| Calendar `events` | meestal 1 week | korter |
| Gmail (`watch`) | vernieuw minstens elke 7 dagen | aanrader: dagelijks |

:::warn
Bouw een mechanisme dat op tijd een nieuw kanaal aanmaakt voordat het oude verloopt. Doe je dat niet, dan stoppen je meldingen stilletjes en mis je wijzigingen zonder foutmelding. Voor Gmail roep je `watch` minstens eens per 7 dagen aan, het liefst dagelijks.
:::

## Betrouwbaarheid en herhaalde meldingen

Webhooks worden over het internet verstuurd en kunnen daardoor soms dubbel of in een andere volgorde aankomen. Een goed ontworpen ontvanger houdt hier rekening mee. Maak je verwerking idempotent, zodat dezelfde melding twee keer verwerken geen schade aanricht.

De verwerking verloopt in een vaste volgorde:

1. **Wijziging.** Er verandert iets, bijvoorbeeld een nieuw bestand in Drive of een gewijzigde afspraak.
2. **Push.** Google stuurt een POST naar jouw HTTPS-endpoint.
3. **Validatie.** Je endpoint controleert het kanaal-ID en het token uit de headers.
4. **Ophalen.** Een vervolgaanroep haalt de echte wijziging op, want de melding bevat alleen een seintje.
5. **Verwerken.** Je verwerkt de wijziging idempotent, bijvoorbeeld loggen of doorsturen.

## Webhooks versus pollen in de praktijk

De keuze tussen webhooks en pollen draait om een afweging tussen snelheid en eenvoud. Webhooks reageren direct en sparen aanvragen, maar vereisen een publiek bereikbaar endpoint dat je beheert en beveiligt. Pollen is eenvoudiger op te zetten, je vraagt simpelweg periodiek of er iets nieuws is, maar je betaalt dat met vertraging en extra aanvragen die vaak niets opleveren.

Voor processen waar elke seconde telt, zoals een binnenkomende betaling of een spoedaanvraag, zijn webhooks de juiste keuze. Voor taken die best een kwartier mogen wachten, zoals een nachtelijke rapportage of het opschonen van een map, is pollen prima en bespaart het je de complexiteit van een endpoint. Kies dus op basis van hoe snel je echt moet reageren.

In de praktijk combineren veel teams beide. Ze gebruiken webhooks voor de directe reactie en een periodieke controle als vangnet voor gemiste meldingen. Zo krijg je het beste van twee werelden: snelheid wanneer alles werkt en betrouwbaarheid wanneer een melding onverhoopt niet aankomt. Deze gelaagde aanpak is robuuster dan blind vertrouwen op een enkel mechanisme en voorkomt dat je wijzigingen mist zonder het te merken.

## Wanneer kies je webhooks

Webhooks zijn ideaal wanneer snelheid telt en je niet onnodig wilt pollen. Voor minder tijdkritische taken volstaat een periodieke controle vaak prima. Wil je webhooks zonder zelf een server te beheren, gebruik dan een no-code platform dat de ontvangst voor je regelt. Combineer webhooks met goed [[workspace-api-tokens-beheer|tokenbeheer]] voor een veilige opzet.

:::faq
### Welke Workspace-API's ondersteunen webhooks?
De Drive API, Calendar API en Gmail API ondersteunen push-notificaties. Drive en Calendar sturen rechtstreeks een POST naar jouw HTTPS-URL. Gmail werkt via Cloud Pub/Sub in plaats van een directe URL.

### Moet ik mijn domein verifiëren in de API Console?
Nee, dat is niet meer nodig. Vroeger moest je het ontvangende domein verifiëren, maar Google vereist dit voor Drive- en Calendar-push-notificaties niet langer. Je hebt wel een HTTPS-endpoint met een geldig certificaat nodig, en je beveiligt het door het token te valideren.

### Hoe vaak moet ik een Gmail-kanaal vernieuwen?
Roep `watch` minstens eens per 7 dagen aan, anders stoppen de meldingen. Google raadt aan om dit dagelijks te doen, zodat je nooit tegen de limiet aanloopt.

### Wat als mijn endpoint even niet bereikbaar is?
Google probeert de melding een aantal keer opnieuw, maar garandeert geen oneindige herhaling. Combineer webhooks daarom met een periodieke controle als vangnet voor gemiste meldingen.

### Krijg ik de bestandsinhoud rechtstreeks in de melding?
Nee. Een push-notificatie is alleen een seintje dat er iets is veranderd. Je doet een vervolgaanroep naar de API om de daadwerkelijke wijziging of inhoud op te halen.

### Kan ik webhooks gebruiken zonder code?
Ja. Tools als [[make-workspace-scenario|Make]], [[zapier-workspace-zap|Zapier]] en [[n8n-workspace-koppeling|n8n]] bieden ingebouwde webhook-ontvangers, zodat je zonder eigen endpoint realtime kunt reageren.
:::