Webhooks

Introduction

A webhook sends an outbound notification to an external service (Discord, Slack, Microsoft Teams, or a URL of your choice) every time an event happens in a repository: a check-in, a check-out, or a periodic activity summary. It is the simplest way to keep a team informed without opening the client: a message drops into your channel when someone submits work.

Webhooks are configured per repository, in the admin panel of the desktop client, under the Webhooks tab. A repository can have several webhooks (for example one to Discord for the whole team, one to a private Slack for the leads).

Access and roles

Managing webhooks is reserved for repository administrators: a super admin (admin role) on any repository, or a project_admin on the repositories they administer. Other roles do not see this tab.

Create a webhook

1. Open the admin panel, select the repository, then the Webhooks tab.
2. Click Add Webhook.
3. Fill in the fields, then Create.

To get the URL on the Discord side: Channel settings → Integrations → Webhooks → New Webhook → Copy Webhook URL. On the Slack side: create an Incoming Webhook in the Slack app settings. On the Teams side: Connectors → Incoming Webhook on the channel.

Tutorial: Discord webhook

This is the most common case. The "get the URL" part happens entirely inside Discord, just once.

On the Discord side: get the URL

1. Open Discord and go to your server. Choose (or create) the text channel that will receive the notifications, for example #uversion.
2. Hover over the channel name and click the gear icon ("Edit Channel").
3. In the left-hand menu, open the Integrations tab.
4. Click Webhooks, then New Webhook. Discord creates one automatically, attached to this channel.
5. Click the created webhook to open it. Give it a name (for example uVersion), and check that the target channel is the right one. An avatar image is optional.
6. Click Copy Webhook URL. The URL looks like https://discord.com/api/webhooks/123456789/AbCdEf....

On the uVersion side: connect the URL

1. In the desktop client, open the admin panel, select the repository, then the Webhooks tab.
2. Click Add Webhook.
3. Name: a label for you (e.g. Discord équipe).
4. URL: paste the URL copied from Discord.
5. Type: choose discord (essential so the message is formatted as a Discord embed).
6. Events: check the events you want, for example checkin.
7. Click Create.
8. On the webhook row, click Send test: a test message should appear in the Discord channel within a few seconds.

If the test fails with an HTTP 401 or 404 status, the URL is wrong or the webhook was deleted on the Discord side: copy the URL again. If nothing arrives even though the test is green, check that you are looking at the right channel and that the webhook has not been disabled in Discord.

Types and formats

The Type determines how uVersion formats the message before sending it. Choose the one that matches the service pointed to by the URL, otherwise the message will arrive malformed (or be rejected by the service).

Events

Check only what your channel needs. In a large studio, checkout can be noisy: many teams keep only checkin and activity_summary.

Custom webhooks

With the custom type, two extra fields appear: Custom Headers (JSON) and Custom Template (JSON). They let you integrate any service that accepts a JSON POST.

Template

The template is the JSON body that is sent. uVersion replaces the variables in double braces with the values of the event. Example:

{"text": "{{event_type}} par {{username}} dans {{repository}}"}

Available variables:

Headers

A JSON object of HTTP headers to attach to the request, for example an authentication token:

{"Authorization": "Bearer VOTRE_JETON"}

Defaults to {} (no headers). Headers reserved for transport (host, content-length, transfer-encoding, connection) are stripped automatically and cannot be overridden.

Test, enable, delete

Each webhook in the list offers the following actions:

• Send test (plane icon): sends a test notification to the service and shows an inline result (green check or cross). Useful to verify the URL and the type before relying on it.
• Toggle: enables / disables the webhook without deleting it.
• Edit: modify any field.
• Delete: permanent deletion (confirmation required).

Security: SSRF guard

A webhook makes an HTTP request be issued by the server. To prevent a malicious URL from being used to probe the server's internal network (SSRF attack), uVersion applies a strict guard on creation, on modification and on test:

• The scheme must be http or https. Any other scheme is refused.
• The hostname is resolved via DNS, and every resulting IP address is checked. The webhook is refused if one points to a non-public address: loopback, private networks (RFC1918), link-local, broadcast, CGNAT range 100.64.0.0/10, cloud metadata 169.254.169.254, ULA / IPv6 link-local, and their IPv4-mapped-IPv6 equivalents.
• HTTP redirects are not followed (so a 307 to an internal host cannot bypass the guard).
• The upstream response body is never returned to the client (no SSRF oracle).

In practice: a webhook URL must point to a public service (Discord, Slack, Teams, or your own endpoint reachable from the Internet). A URL to localhost, a private IP (10.x, 192.168.x, 172.16-31.x) or an internal service is refused with a "Webhook URL refused: …" message.

Common pitfalls

The type does not match the service

Sending a Discord format to a Slack URL (or the reverse) produces a malformed message or a rejection on the service side. The Type field must match the URL. When in doubt, do a Send test.

No event checked

A webhook with no event never triggers. The client blocks saving as long as no event is selected ("At least one event is required").

Internal URL refused

If you test against a service on your own machine or your LAN, the SSRF guard refuses it. Expose the service on a public URL (or a tunnel) to use it as a webhook target.

Forgotten disabled webhook

A disabled webhook stays in the list but sends nothing. If notifications have gone silent, check the activation toggle first before suspecting the URL.