Webhooks (beheer)

FixControl behandelt twee soorten webhooks:

• Inkomend: andere systemen (Slack, Microsoft Teams, GitHub, GitLab, Bitbucket, Office 365, je CI/CD-hosts en supportdesks) leveren events af bij FixControl. Elk wordt ingericht bij de bijbehorende integratie.
• Uitgaand: je eigen systemen ontvangen FixControl-events. Die richt je in onder Instellingen → Kanalen → Webhooks & API → Uitgaande webhooks.

De stap-voor-stap-inrichting van uitgaande webhooks, inclusief een werkende handtekeningcontrole, staat in de gebruikersgids. Deze pagina is de operationele kijk voor admins: hoe levering zich gedraagt en hoe je een mislukte levering onderzoekt.

Inkomend: handtekeningcontrole

Elke inkomende webhook wordt gecontroleerd voordat FixControl hem accepteert. Een verzoek dat niet klopt krijgt 401 en wordt weggegooid; het wordt nooit verwerkt.

Voor CI/CD-hosts, zie DevOps & CI/CD; voor Jira, Freshdesk, Odoo en TOPdesk, zie Issue-trackers.

Geheimen worden versleuteld opgeslagen. Roteren is een harde overstap: zodra je een geheim in FixControl roteert, wordt het oude niet meer geaccepteerd. Werk het geheim bij het verzendende systeem meteen bij, anders worden leveringen geweigerd tot je dat doet.

Inkomend: verwerking en opnieuw proberen

Events van Slack en Teams worden direct bevestigd en op de achtergrond verwerkt. Mislukt de verwerking door een tijdelijke oorzaak, dan probeert FixControl het opnieuw, tot drie pogingen met een paar seconden ertussen, voordat het event als mislukt wordt vastgelegd. Een blijvende authenticatiefout (bijvoorbeeld omdat de app is verwijderd) wordt niet opnieuw geprobeerd: de verbinding wordt dan op Herverbinden vereist gezet.

Uitgaand: leveringsmodel

Matcht een FixControl-event met een van je uitgaande webhooks, dan wordt een levering in de wachtrij gezet en met POST naar jouw URL gestuurd:

event vuurt af
  → match webhooks (je organisatie + eventfilter)
  → per match: levering in de wachtrij
  → POST naar de URL, status en responscode vastleggen

Een respons met HTTP 2xx sluit de levering af als Geslaagd. Elke andere respons, of geen respons binnen 10 seconden, wordt opnieuw geprobeerd. Elke levering krijgt in totaal drie pogingen:

poging 1   direct
poging 2   ~1s na de eerste
poging 3   ~5s na de tweede

Na de derde mislukte poging stopt de levering. Er is geen latere poging en geen knop om opnieuw te versturen: lag de ontvanger langer plat, dan wordt het event niet opnieuw verstuurd.

Wil je zien wat er gebeurde, open dan de webhook en klik op Leveringen bekijken. Elke regel toont het event, de status, de responscode, het aantal pogingen, de fout, de tijd en het request-ID. FixControl bewaart de body van het verzoek of de respons niet.

Met Test versturen stuur je op elk moment een testevent naar je endpoint.

Uitgaand: het signing secret

Het signing secret wordt één keer getoond, als je de webhook aanmaakt. Daarna toont het scherm alleen een kort voorbeeld. Er is geen knop om te roteren: wil je het geheim wijzigen, maak dan een nieuwe webhook aan met dezelfde URL en events, zet je ontvanger om en verwijder de oude.

Operationele signalen

Elke integratie heeft een gezondheidspaneel dat de status per capability toont, plus nieuwe pogingen en mislukte leveringen, en of de verbinding opnieuw gekoppeld moet worden. Kijk daar eerst als er geen events meer lijken binnen te komen.

Veelvoorkomende operationele problemen

Een inkomende webhook geeft elke keer 401. Het geheim bij het verzendende systeem klopt niet. Roteer voor GitLab het geheim op de GitLab CI-kaart en plak de nieuwe waarde in GitLab. Voor geheimen die FixControl beheert (GitHub, Bitbucket, de webhooks van supportdesks), vraag het je FixControl-contactpersoon.

Uitgaande leveringen slagen, maar de ontvanger verwerkt ze niet. Vrijwel altijd faalt de handtekeningcontrole bij de ontvanger. Controleer dat de ontvanger HMAC-SHA256 berekent over <timestamp>.<ruwe request-body>: de t=-waarde uit de header X-FixControl-Signature, een punt, dan de body byte voor byte, niet opnieuw geserialiseerde JSON. Zie de gebruikersgids voor webhooks voor een werkende controle.

Office 365-subscriptions verlopen. Microsoft Graph-subscriptions leven ongeveer drie dagen en FixControl vernieuwt ze volgens een schema. Wordt een vernieuwing gemist en verloopt de subscription, dan gaat de integratie naar Herverbinden vereist. Koppel opnieuw via de integratiepagina. Events die in het gat binnenkwamen, worden achteraf niet opgehaald, omdat Microsoft ze niet bewaart.

FAQ

Kan ik instellen hoe vaak een levering opnieuw wordt geprobeerd? Nee. Elke uitgaande levering krijgt dezelfde drie pogingen.

Kan ik de exacte body zien die is verstuurd? Nee. Het leveringslog bewaart het event, de status, de responscode, de pogingen en de fout, niet de body. Log de body aan de ontvangende kant als je die nodig hebt, met de header X-FixControl-Delivery als sleutel.

Worden webhook-geheimen automatisch geroteerd? Nee. Roteren is altijd een bewuste actie van een admin, omdat een ontvanger op hetzelfde moment moet worden bijgewerkt.

Gerelateerd: Webhooks (gebruikersgids) · Public API (beheer) · DevOps & CI/CD