Inkomende webhooks

Inkomende webhooks laten externe tools automatische berichten in een HansaChat-kanaal plaatsen. Gebruik ze voor implementatie-updates, monitoringwaarschuwingen, ticketmeldingen, inzendingen van formulieren en andere gebeurtenissen die in de teamchat horen te verschijnen.

Alleen workspacebeheerders kunnen inkomende webhooks aanmaken en beheren.

Een webhook aanmaken

1. Open Instellingen linksonder in de zijbalk.
2. Selecteer Webhooks.
3. Kies Webhook maken.
4. Voer een duidelijke webhooknaam in, zoals CI Deployments.
5. Kies het kanaal waarin berichten moeten verschijnen.
6. Voer optioneel een icon-URL in.
7. Kies Webhook maken.

De webhook-URL kopiëren

Na het aanmaken toont HansaChat de webhook-URL één keer. Kopieer de URL en bewaar die veilig in de externe tool die gebeurtenissen gaat versturen.

Als u dit scherm sluit zonder de URL op te slaan, roteert u de URL om een nieuw geheim te genereren. De vorige URL werkt direct na de rotatie niet meer.

Webhooks beheren

Vanaf de webhooks-pagina kunnen beheerders:

• de webhooknaam, het kanaal, de icon-URL of de actieve status bewerken;
• een webhook uitschakelen, zodat nieuwe berichten worden geweigerd zonder de webhook te verwijderen;
• URL roteren om het oude geheim ongeldig te maken en een nieuwe URL te genereren;
• een webhook verwijderen. Bestaande chatberichten worden niet verwijderd.

Technische referentie

Stuur een POST-verzoek naar de webhook-URL:

https://{workspace-domain}/api/webhooks/{publicID}/{secret}

De URL bevat de inloggegevens van de webhook. Er is geen extra authenticatieheader nodig. Houd de volledige URL geheim.

Minimaal verzoek

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deployment completed successfully"}'

Zodra HansaChat ok teruggeeft, verschijnt het bericht in het gekozen kanaal.

Slack-compatibele payload

Het endpoint accepteert Slack-compatibele JSON-payloads met text, blocks en attachments.

{
  "text": "Deployment completed successfully",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Deployment completed"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Branch `main` is now live."
      }
    }
  ]
}

Minstens één van text, blocks of attachments moet leesbare tekst bevatten.

Ondersteunde velden

De maximale grootte van de payload is 1 MB.

Snelheidslimieten

De verwerking van inkomende webhooks is per webhook-URL aan een snelheidslimiet gebonden.

Elke webhook kan maximaal 10 geauthenticeerde verzoeken per minuut en maximaal 100 geauthenticeerde verzoeken per uur verwerken. Wanneer een van beide limieten is bereikt, geeft HansaChat 429 resource_exhausted terug.

Neem contact met ons op als u de snelheidslimiet wilt verhogen.

Payload-limieten worden apart gehandhaafd: de maximale grootte van de body is 1 MB, blocks accepteert maximaal 50 items, attachments accepteert maximaal 100 items en de payload moet leesbare tekst bevatten.

Idempotentie

Voeg een Idempotency-Key-header toe wanneer uw systeem dezelfde gebeurtenis mogelijk opnieuw verstuurt:

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-1247' \
  -d '{"text":"Deployment #1247 completed"}'

Als HansaChat dezelfde idempotentiesleutel opnieuw ontvangt voor dezelfde webhook, geeft het 200 ok terug zonder een dubbel bericht aan te maken.

Antwoorden

Geslaagde verzoeken geven terug:

ok

Veelvoorkomende fouten:

Beveiligingstips

• Behandel webhook-URL's zoals wachtwoorden.
• Bewaar URL's in de secret manager van uw externe tool.
• Roteer de URL als deze is gelekt of verloren is gegaan.
• Schakel ongebruikte webhooks uit.
• Gebruik een aparte webhook per extern systeem, zodat toegang netjes kan worden ingetrokken.