Webhooks

Webhooks

A webhook sends issue data as an HTTP POST request with a JSON body to an address you choose. You can use it to:

• notify company channels — Slack, Google Chat, Microsoft Teams,
• pass events to your own system (ERP, CRM, shop, automations).

Webhooks are configured under System → Webhooks.

How it works

Sending is made of three parts:

1. Webhook — where to send: address, kind and authentication. One webhook (e.g. a Slack channel) can be used by many rules.
2. Webhook template — what to send: a JSON body with issue data, created in Templates.
3. Business rule — when to send: the Sending webhook action links a webhook with a template and runs on the chosen event (Business rules).

This way the same channel can receive different messages — e.g. "new issue" from one rule and "step changed" from another.

Adding a webhook

1. Go to System → Webhooks and click New webhook.
2. Enter a Name and choose the Kind.
3. Paste the URL provided by the receiver (https required).
4. For the Generic kind, optionally choose Authentication.
5. Save. For a generic webhook you will see the signing secret — copy it right away, it is shown only once.

Webhook kinds

Slack, Google Chat and Teams webhook addresses contain a secret token. That is why Reklamator does not show the full address after saving — only its beginning (e.g. https://hooks.slack.com/…). When editing, leave the address field empty to keep it unchanged.

Internal addresses (e.g. localhost, private network addresses) are rejected — the webhook must be reachable from the internet.

Authentication (generic webhook)

A custom header cannot override technical headers (Host, Content-Type, Content-Length, Connection, User-Agent, Transfer-Encoding or X-Reklamator-* headers). Passwords and tokens are stored encrypted and are never shown after saving.

Slack, Google Chat and Teams use no authentication or signature — the token is part of the address.

Message template

The body sent by a webhook is a template of type Webhook. When creating the template, choose Starter Templates — there are ready-made patterns for each kind (generic JSON, Slack, Google Chat, Teams).

Example for Google Chat or Slack:

{"text": {{ ("New issue " ~ issue_internal_number ~ " (" ~ issue_type_name ~ ")")|json }}}

The rules for writing a webhook template are described in Templates → Webhook template.

Testing a webhook

Choose Send test from the row menu on the list. You can send:

• sample data — without choosing a template, to check the address and authentication,
• a template on a chosen issue — choose a webhook template and enter an issue number; you will see exactly what the rule will send.

The result is shown immediately: status, receiver response code, time and response body. If the template does not produce valid JSON, the test reports it right away. Tests do not affect the webhook failure counter.

Deliveries and retries

Each rule run is a delivery. The webhook delivery list is available from the row menu (Deliveries) — it shows the status, event, number of attempts, last response code and the data sent.

Retries. If the receiver is temporarily unavailable (no connection, 10 s timeout exceeded, code 408, 425, 429 or 5xx), Reklamator retries with growing intervals: after about 5 s, 25 s, 2 min and 10 min — up to 5 attempts in total. Other 4xx codes and redirects (3xx) end the delivery without retrying, as they usually mean a configuration error.

Redeliver on the delivery list sends the same data once more as a new delivery — e.g. after a fix on the receiver's side. It does not work for a disabled webhook.

Deliveries are kept for 30 days.

Automatic disabling

After 20 consecutive failed deliveries the webhook disables itself and is marked Disabled automatically. The system log then gets a WEBHOOK_AUTO_DISABLED entry. After fixing the receiver, enable the webhook in its edit form — the failure counter resets.

System log

Every sending attempt is written to the system log in the WEBHOOK module: successful as INFO, failed as ERROR. The entry contains the webhook name, event, attempt number, response code and time, and a fragment of the receiver's response.

Errors detected before sending are logged too, e.g. WEBHOOK_INVALID_PAYLOAD — the template did not produce valid JSON for the given issue.

For integrators (generic webhook)

The request sent by Reklamator:

The signature is an HMAC-SHA256 of the text <timestamp>.<body> using the webhook secret, hex-encoded. Verification on the receiver side (Python):

import hashlib, hmac, time

def is_valid(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = 'v1=' + hmac.new(secret.encode(), f'{timestamp}.'.encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Compute the signature from the raw request body, before parsing JSON. Respond with 2xx as quickly as possible — move long processing to your own queue.

The secret can be replaced from the row menu (Generate new secret). The old secret stops working immediately, so update it on the receiver's side.

FAQ

Can I send to several channels at once?

Yes. Add a separate webhook for each channel and add several Sending webhook actions to the rule.

Can one template be used by many webhooks?

Yes. The template and the webhook are independent — you choose them separately in the rule action.

Why can't I see the full webhook address?

Slack, Google Chat and Teams addresses contain a secret token, so they are stored encrypted and not displayed. To change the address, enter a new one in the webhook edit form.

The webhook doesn't arrive — where do I look?

Check the webhook's Deliveries list and the system log (WEBHOOK module). No delivery with a WEBHOOK_INVALID_PAYLOAD error means the template is wrong — check it with Send test on the same issue.

Can I delete a webhook used in a rule?

No. Remove it from the business rule action first. You can also disable a webhook without deleting it.

Can the receiver get the same message twice?

Rarely — e.g. when the receiver accepted the request but the response did not reach Reklamator. Every retry carries the same X-Reklamator-Delivery header, which the receiver can use to drop the duplicate.