Webhooki przychodzące

Webhooki przychodzące pozwalają narzędziom zewnętrznym publikować zautomatyzowane wiadomości w kanale HansaChat. Używaj ich do aktualizacji wdrożeń, alertów monitorowania, powiadomień ze zgłoszeń, danych z formularzy i innych zdarzeń, które powinny pojawić się na czacie zespołu.

Webhooki przychodzące mogą tworzyć i zarządzać nimi tylko administratorzy przestrzeni roboczej.

Tworzenie webhooka

1. Otwórz Ustawienia na pasku bocznym w lewym dolnym rogu.
2. Wybierz Webhooki.
3. Wybierz Utwórz webhook.
4. Wpisz czytelną nazwę webhooka, np. CI Deployments.
5. Wybierz kanał, w którym mają być publikowane wiadomości.
6. Opcjonalnie podaj adres URL ikony.
7. Wybierz Utwórz webhook.

Kopiowanie adresu URL webhooka

Po utworzeniu HansaChat pokazuje adres URL webhooka tylko raz. Skopiuj go i zapisz w bezpiecznym miejscu w narzędziu zewnętrznym, które będzie wysyłać zdarzenia.

Jeśli zamkniesz ten ekran bez zapisania adresu URL, wygeneruj nowy adres, aby utworzyć nowy sekret. Poprzedni adres przestaje działać natychmiast po generowaniu nowego.

Zarządzanie webhookami

Ze strony Webhooki administratorzy mogą:

• Edytować nazwę webhooka, kanał, adres URL ikony lub stan aktywności.
• Wyłączyć webhook, aby odrzucał nowe wiadomości bez jego usuwania.
• Wygenerować nowy adres URL, aby unieważnić stary sekret i utworzyć nowy adres.
• Usunąć webhook. Już opublikowane wiadomości na czacie nie są usuwane.

Dokumentacja techniczna

Wyślij żądanie POST na adres URL webhooka:

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

Adres URL zawiera dane uwierzytelniające webhooka. Żadne dodatkowe nagłówki uwierzytelniające nie są wymagane. Trzymaj pełny adres URL w tajemnicy.

Minimalne żądanie

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

Gdy HansaChat zwróci ok, wiadomość pojawi się w wybranym kanale.

Ładunek zgodny ze Slackiem

Punkt końcowy przyjmuje ładunki JSON zgodne ze Slackiem, z polami text, blocks i 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."
      }
    }
  ]
}

Co najmniej jedno z pól text, blocks lub attachments musi zawierać czytelny tekst.

Obsługiwane pola

Maksymalny rozmiar ładunku to 1 MB.

Limity żądań

Przyjmowanie żądań przez webhooki przychodzące jest ograniczone limitem dla każdego adresu URL webhooka.

Każdy webhook może przyjąć do 10 uwierzytelnionych żądań na minutę i do 100 uwierzytelnionych żądań na godzinę. Po osiągnięciu któregokolwiek z tych limitów HansaChat zwraca 429 resource_exhausted.

Jeśli chcesz zwiększyć limit żądań, skontaktuj się z nami.

Limity ładunku są egzekwowane osobno: maksymalny rozmiar treści to 1 MB, pole blocks przyjmuje do 50 elementów, pole attachments do 100 elementów, a ładunek musi zawierać czytelny tekst.

Idempotencja

Dodaj nagłówek Idempotency-Key, gdy Twój system może ponowić to samo zdarzenie:

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"}'

Jeśli HansaChat ponownie otrzyma ten sam klucz idempotencji dla tego samego webhooka, zwraca 200 ok bez tworzenia zduplikowanej wiadomości.

Odpowiedzi

Udane żądania zwracają:

ok

Typowe błędy:

Wskazówki dotyczące bezpieczeństwa

• Traktuj adresy URL webhooków jak hasła.
• Przechowuj adresy URL w menedżerze sekretów swojego narzędzia zewnętrznego.
• Wygeneruj nowy adres URL, jeśli stary wyciekł lub został utracony.
• Wyłączaj nieużywane webhooki.
• Używaj osobnego webhooka dla każdego systemu zewnętrznego, aby dostęp można było jednoznacznie odebrać.