Webhooks

Een inkomende webhook stelt een ander systeem in staat berichten in een kanaal te plaatsen door JSON te verzenden naar een geheime URL. Een uitgaande webhook doet het tegenovergestelde: het stuurt berichten naar uw URL, namelijk berichten die beginnen met een triggerwoord of die iemand via het berichtmenu voor deze webhook kiest, en het plaatst wat u als antwoord verstuurt.

Webhooks beheren

Klik op uw avatar rechtsboven en ga daarna naar Integraties. De integratiepagina's van de huidige community tonen Inkomende webhooks en Uitgaande webhooks. Elke webhook is gekoppeld aan één community.

Standaard kunnen communitybeheerders en systeembeheerders webhooks aanmaken. Een systeembeheerder kan dit recht toekennen aan andere rollen in de machtigingsinstellingen van de Systeemconsole. Een systeembeheerder kan ook elk type webhook uitschakelen in Systeemconsole › Integraties › Integratiebeheer: Inschakelen inkomende webhooks en Inschakelen uitgaande webhooks zijn beide standaard ingeschakeld.

Een inkomende webhook aanmaken

1. Ga in Integraties naar Inkomende webhooks en klik op Inkomende webhook toevoegen.
2. Vul een Titel en een Omschrijving in: deze worden alleen weergegeven op de integratiepagina's.
3. Kies het Kanaal waar de berichten standaard naartoe gaan. Voor een privé-kanaal moet u lid zijn van dat kanaal.
4. Vink Vergrendel aan dit kanaal aan als afzenders nergens anders berichten mogen plaatsen.
5. Stel optioneel een Gebruikersnaam en een URL voor een Profiel afbeelding in voor de berichten (zie Naam en pictogram).
6. Klik op Opslaan. Kopieer de weergegeven URL: https://chat.example.com/hooks/<key>.

Met de API: POST /api/v4/hooks/incoming met {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; het id-veld in het antwoord is de sleutel. Vanuit de opdrachtregel: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Een bericht naar een inkomende webhook sturen

curl -X POST https://chat.example.com/hooks/xgh5ycrx1jf7mbs9w8z4c8e7ho \
  -H 'Content-Type: application/json' \
  -d '{"text": "Deploy of **api 2.4.0** finished :white_check_mark:"}'

De server antwoordt met 200 en het body ok. Het accepteert ook application/x-www-form-urlencoded met de JSON in een payload-veld, zoals de webhooks van Slack, zodat tools die voor Slack zijn gemaakt, meestal ongewijzigd werken.

Elk bericht dat een webhook plaatst, heeft een BOT-label naast de naam, zelfs wanneer het onder de naam van de maker wordt weergegeven, zodat mensen het kunnen onderscheiden van een bericht van een echte persoon. Webhookberichten activeren nooit uitgaande webhooks.

Naam en pictogram

Een webhook post als de persoon die het heeft aangemaakt, tenzij de server overrides toestaat. Twee instellingen in Systeemconsole › Integraties › Integratiebeheer, beide standaard uitgeschakeld, veranderen dat:

• Aanzetten van integraties die overschrijven van gebruikersnaam mogelijk maakt (ServiceSettings.EnablePostUsernameOverride): de Gebruikersnaam van de webhook of de username in de aanvraag wordt getoond; zonder beide is de naam webhook.
• Aanzetten van integraties die overschrijven van profiel afbeeldingen mogelijk maakt (ServiceSettings.EnablePostIconOverride): de Profiel afbeelding van de webhook, of de icon_url of icon_emoji in de aanvraag, wordt getoond.

Een waarde in de aanvraag heeft voorrang op de waarde die op de webhook is opgeslagen.

Bijlagen

Bijlagen voegen gestructureerde inhoud toe onder de tekst. Ze volgen het berichtbijlatformaat van Slack:

{
  "text": "Build failed on `main`",
  "attachments": [{
    "fallback": "main #1902 failed",
    "color": "#d24b4e",
    "author_name": "GitHub Actions",
    "author_icon": "https://chat.example.com/static/ci.png",
    "title": "main #1902 failed",
    "title_link": "https://ci.example.com/runs/1902",
    "text": "Commit `0f4d8e2` by Jonas Weber",
    "fields": [
      {"title": "Branch", "value": "zephyr-3.7", "short": true},
      {"title": "Duration", "value": "3m 40s", "short": true}
    ],
    "footer": "Lumen CI",
    "ts": 1760000000
  }]
}

Kaarten: fasen en grafieken

Antimatter voegt twee velden toe aan bijlagen, die door de standaardinterface worden weergegeven:

• stages: de stappen van een pipeline als pills, tot 20. Elke stap is {"name", "status"}, met een status van passed, failed, running, pending, skipped of canceled.
• chart: een kleine lijngrafiek met recente waarden, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. De drempelwaarde wordt weergegeven als een gestreepte lijn, voor de limiet van een melding.

{
  "attachments": [{
    "color": "danger",
    "title": "main #1902 failed",
    "stages": [
      {"name": "build", "status": "failed"},
      {"name": "unit", "status": "skipped"},
      {"name": "publish", "status": "skipped"}
    ]
  }, {
    "color": "warning",
    "title": "API latency above 400 ms",
    "chart": {"values": [210, 230, 260, 390, 450, 470], "threshold": 400, "label": "p95 latency, ms"}
  }]
}

De klassieke interface en andere clients negeren deze twee velden, dus voeg de essentiële informatie ook toe aan text of fields.

Een uitgaande webhook aanmaken

Een uitgaande webhook bewaakt de Publiek kanalen van een community. Het stuurt een bericht naar uw URL wanneer het eerste woord van het bericht exact overeenkomt met een van de triggerwoorden, of wanneer iemand het kiest in het menu van het bericht (een berichtactie).

1. Ga naar Integraties, kies Uitgaande webhooks en klik vervolgens op Uitgaande webhook toevoegen.
2. Vul de Titel en de Omschrijving in.
3. Kies de Content Type van de aanvraag: application/x-www-form-urlencoded of application/json.
4. Kies een Kanaal, voer Activeer woorden (één per regel) in, of doe beide. Met een kanaal en geen activeringswoorden wordt elk bericht van dat kanaal verzonden. Met beide moet het bericht aan beide voorwaarden voldoen.
5. Onder Activatiewoord kiest u Eerste trigger woord komt exact overeen, Eerste woord start met een trigger woord of Uit het berichtmenu. Bij Uit het berichtmenu verdwijnen de triggerwoorden, is het Kanaal optioneel (zonder kanaal wordt de actie aangeboden in elk publiek kanaal van de community) en is de Titel verplicht: dit is de naam van de actie in het menu.
6. Voer de Callback URL's (Een per regel) in. Elke URL ontvangt elk overeenkomend bericht.
7. Stel optioneel de Gebruikersnaam en de Profiel afbeelding in die voor antwoorden worden gebruikt. Voor een actie uit het berichtmenu vervangt het veld Pictogram de Profiel afbeelding: de URL van een .png- of .jpg-afbeelding of, in de standaardinterface van Antimatter, een geüploade afbeelding. Het menu toont deze in grijs; zonder afbeelding krijgt de actie een neutraal pictogram.
8. Kies Opslaan en kopieer het weergegeven token. Uw service gebruikt dit om te controleren of aanvragen van uw server komen.

Via de API: POST /api/v4/hooks/outgoing met {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 voor een exacte match, 1 voor "begint met", 2 voor "via het berichtmenu"). Een webhook met trigger_when 2 gebruikt geen activatiewoorden en vereist een display_name. Upload het pictogram met POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, veld image: PNG, JPEG of GIF, opgeslagen als PNG van 128 px); de icon_url wijst dan naar GET /api/v4/hooks/outgoing/{hook_id}/icon.

De uitgaande aanvraag

Antimatter stuurt een POST met deze velden, als JSON of form-encoded, afhankelijk van de content type:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "text": "deploy api 2.4.0",
  "trigger_word": "deploy",
  "file_ids": ""
}

Vergelijk token met de token van de webhook voordat u iets doet. In de versie met formuliercodering is timestamp in seconden in plaats van milliseconden. De server wacht op uw antwoord zolang Time-out integratieverzoek toestaat (standaard 30 seconden, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Antwoorden op een uitgaande webhook

Om een antwoord te plaatsen, antwoordt u met JSON. Om niets te plaatsen, antwoordt u met een leeg body.

{
  "text": "Deploying **api 2.4.0** to staging…",
  "response_type": "comment",
  "username": "deploy-bot",
  "icon_url": "https://chat.example.com/static/deploy.png"
}

• text en attachments: het antwoord. Zonder een van beide wordt er niets geplaatst.
• response_type: comment plaatst het antwoord in het draadje van het triggerende bericht; anders gaat het naar het kanaal.
• username, icon_url: worden weergegeven wanneer de server overrides toestaat; anders worden de eigen waarden van de webhook gebruikt.
• props, type, priority: zoals bij ingaande webhooks.

Het antwoord wordt geplaatst door de maker van de webhook, onder de overriden naam wanneer er een is. Voor iets langer dan een kort antwoord, antwoordt u onmiddellijk en plaatst u later met een ingaande webhook of de API.

Acties voor berichten

Een actie voor berichten is een uitgaande webhook met Activatiewoord ingesteld op via het berichtmenu. Deze wordt nooit geactiveerd door verzonden berichten. In plaats daarvan zien gebruikers deze in het menu van een bericht: Acties voor berichten (⋯) › Meer acties, onder de kop Integraties, met het bijbehorende pictogram. Het klassieke interface toont geen acties voor berichten. Als een gebruiker deze kiest, wordt dat ene bericht naar de callback-URL’s gestuurd. Er verschijnt een korte melding met Verzonden naar de naam van de actie, of wordt de ephemeral_text getoond.

• Waar het verschijnt: in het kanaal van de webhook of, zonder kanaal, in elk publiek kanaal van de werkruimte. Alleen publieke kanalen hebben acties voor berichten.
• Gastgebruikers krijgen alleen de acties te zien die gekoppeld zijn aan een kanaal waar ze lid van zijn, niet de werkruimtebrede acties.
• Gearchiveerde en alleen-lezen kanalen: het bericht kan nog steeds worden verzonden. Bij het archiveren van een kanaal worden de webhooks die eraan gekoppeld zijn, verwijderd. Een gearchiveerd kanaal behoudt daarom alleen de werkruimtebrede acties. Een antwoord dat de gebruiker daar niet zelf kan plaatsen, wordt alleen aan die gebruiker getoond.
• Snelheidslimiet: elke gebruiker kan 10 acties voor berichten per minuut uitvoeren, na een burst van 5. Daarbovenop antwoordt de server met 429.
• Private netwerken: net als bij andere uitgaande webhooks moeten interne adressen zijn toegestaan in Niet-vertrouwde interne verbindingen toestaan naar.

De aanvraag

De payload wordt verzonden als JSON of form-encoded, zoals het content type van de webhook aangeeft:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "trigger": "message_action",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "post_root_id": "",
  "post_create_at": 1760009000000,
  "post_user_id": "…",
  "post_user_name": "jonas",
  "permalink": "https://chat.example.com/lumen-labs/pl/…",
  "text": "The staging database is full again",
  "files": [{"id": "…", "name": "df.txt", "link": "https://chat.example.com/api/v4/files/…"}],
  "priority": "",
  "requested_ack": false,
  "burn_on_read": false
}

• user_id en user_name zijn de gebruiker die de actie heeft gekozen; post_user_id en post_user_name zijn de auteur van het bericht.
• Alleen dat ene bericht wordt verzonden, nooit de rest van het draadje.
• files toont de bestanden van het bericht alleen als de gebruiker die de actie heeft gekozen, deze mag downloaden. Het downloaden van een link vereist een sessie of een token, net als elk ander bestand van de API.
• Een bericht dat na het lezen wordt vernietigd, wordt verzonden zonder tekst en bestanden, met burn_on_read ingesteld op true.
• Bij form-encoded data worden de bestanden als herhaalde file_id, file_name en file_link-velden meegegeven, in dezelfde volgorde.

Het antwoord

Antwoord zoals bij elke uitgaande webhook (zie Antwoorden op een uitgaande webhook): text of attachments plaatst een antwoord in het kanaal, en "response_type": "comment" plaatst het in het draadje van het bericht. Je kunt ook antwoorden met ephemeral_text (beperkt tot 300 tekens): dit wordt alleen getoond aan de persoon die de actie heeft gekozen, in de melding. Een leeg berichtlichaam plaatst niets.

{"ephemeral_text": "Ticket OPS-412 created"}

Met de API

• GET /api/v4/channels/{channel_id}/message_actions: de acties die je in een kanaal kunt kiezen, met id, display_name, description en icon_url. Er worden geen tokens of callback-URL's teruggegeven.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: voert een actie uit op een bericht dat je kunt lezen. Het antwoord is {"ephemeral_text"}.

Wanneer een webhook niet werkt

• 501 van de hook URL: ingaande webhooks zijn uitgeschakeld op de server.
• 400 "Failed to decode the payload…": de JSON is ongeldig, of het veld in het formulier heet niet payload. "No text specified." betekent dat het verzoek noch text noch attachments bevat.
• 403: de webhook is vergrendeld aan een ander kanaal, of de eigenaar kan het kanaal niet meer lezen.
• Een uitgaande webhook wordt nooit geactiveerd: het kanaal is privé, de trigger is niet het eerste woord, het bericht komt van een webhook, of de webhook is ingesteld om te activeren Uit het berichtmenu.
• Een berichtactie staat niet in het menu: het kanaal is privé, de actie is gekoppeld aan een ander kanaal, de persoon is een gast en de actie heeft geen kanaal, of uitgaande webhooks zijn uitgeschakeld.
• 404 bij het uitvoeren van een berichtactie: de actie bestaat niet, of de actie dekt het kanaal van dat bericht niet voor die persoon. 429: de persoon heeft meer dan 10 acties in een minuut uitgevoerd. 502: geen van de callback-URL's kon worden bereikt (de reden staat in het logboek).
• Logboeken: met Webhook debugging inschakelen aan (LogSettings.EnableWebhookDebugging), en het logniveau op DEBUG, logt de server de payloads van mislukte ingaande verzoeken. Mislukte uitgaande oproepen worden gelogd als Outgoing Webhook POST failed.