Incoming webhook instellen voor Google Chat

Wat is een incoming webhook?

Een incoming webhook is een URL waarnaar je een HTTP POST-verzoek kunt sturen om automatisch een bericht in een Google Chat Space te plaatsen. Elke applicatie of dienst die HTTP-verzoeken kan versturen, kan zo berichten sturen naar Chat. Je hoeft hiervoor geen volledige Chat-app te bouwen.

Veelvoorkomende toepassingen:

• Monitoring-alerts (server down, hoge CPU)
• CI/CD-notificaties (build geslaagd of mislukt)
• Sales-notificaties (nieuwe lead binnengekomen)
• Geautomatiseerde dagelijkse rapporten
• Integraties met externe tools (GitHub, Jira, PagerDuty)

Webhook aanmaken

Bericht sturen via de webhook

De payload is altijd JSON. De eenvoudigste vorm is een object met een text-veld.

Curl (command line)

curl -X POST \
  'https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=API_KEY&token=TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Automatisch bericht vanuit mijn systeem!"}'

Let op de backslashes aan het einde van elke regel: die zijn nodig zodat het commando als een geheel wordt uitgevoerd.

Python

import requests
import json
from datetime import datetime

WEBHOOK_URL = 'https://chat.googleapis.com/v1/spaces/.../messages?key=...&token=...'

def stuur_chat_bericht(tekst):
    payload = {'text': tekst}
    response = requests.post(
        WEBHOOK_URL,
        data=json.dumps(payload),
        headers={'Content-Type': 'application/json'}
    )
    return response.status_code == 200

def stuur_monitoring_alert(service, status, details):
    icoon = '\U0001F7E2' if status == 'ok' else '\U0001F534'
    tijdstip = datetime.now().strftime('%H:%M:%S')
    tekst = f'{icoon} *{service}* status: *{status}*
{details}
_Tijdstip: {tijdstip}_'
    return stuur_chat_bericht(tekst)

stuur_monitoring_alert('Webserver', 'offline', 'Reactietijd: time-out na 30s')

Voor opmaak in text gebruikt Chat zijn eigen markup: *vet*, _cursief_ en `code`. Sinds september 2025 ondersteunen tekstwidgets in kaarten ook gewone Markdown.

Kaarten versturen (cardsV2)

Voor rijkere notificaties gebruik je kaarten via het cardsV2-veld:

def stuur_kaart(titel, tekst, knop_tekst=None, knop_url=None):
    card = {
        'cardsV2': [{
            'cardId': 'notificatie',
            'card': {
                'header': {'title': titel},
                'sections': [{
                    'widgets': [
                        {'textParagraph': {'text': tekst}}
                    ]
                }]
            }
        }]
    }

    if knop_tekst and knop_url:
        card['cardsV2'][0]['card']['sections'][0]['widgets'].append({
            'buttonList': {
                'buttons': [{
                    'text': knop_tekst,
                    'onClick': {'openLink': {'url': knop_url}}
                }]
            }
        })

    response = requests.post(
        WEBHOOK_URL,
        data=json.dumps(card),
        headers={'Content-Type': 'application/json'}
    )
    return response.status_code == 200

Rate-limiting en betrouwbaarheid

Google Chat hanteert een limiet van ongeveer 1 verzoek per seconde, gedeeld door alle webhooks in dezelfde Space. Het is dus geen aparte teller per webhook: meerdere webhooks in dezelfde Space delen samen die ruimte. Overschrijd je de limiet, dan krijg je een HTTP-status 429 Too Many Requests terug.

Praktische aanpak:

• Verwerk je batches, voeg dan een korte pauze tussen berichten toe (bijvoorbeeld iets meer dan een seconde).
• Vang status 429 op en probeer het opnieuw met exponentiële backoff (steeds langer wachten).
• Bundel meerdere meldingen liever in één kaart in plaats van veel losse berichten.

Webhook beveiligen

Webhook-URLs zijn gevoelig: iedereen met de URL kan berichten sturen. Beveiligingstips:

• Sla de webhook-URL op in een secrets manager (bijvoorbeeld Google Secret Manager of HashiCorp Vault).
• Gebruik omgevingsvariabelen in je applicatie, nooit hardcoded waarden.
• Roteer de webhook-URL regelmatig door een nieuwe aan te maken en de oude te verwijderen.
• Monitor op een ongewone berichtfrequentie, zodat je misbruik snel opmerkt.