Gitter notifications: incoming webhook or REST API?

The decision

You need a CI pipeline or script to post messages to a Gitter room—for example, deploy failures or build alerts. Gitter offers two supported paths: an incoming webhook URL from room settings, or the REST API with an OAuth bearer token.

Useful takeaway: choose the incoming webhook for simple, one-way text notifications when you do not want to manage tokens. Choose the REST API when you need Markdown formatting, message history, editing, or replies, and you can store and rotate credentials securely.

Constraints and assumptions

• You are posting to a Gitter room you can access.
• GitLab is the primary identity provider for Gitter; legacy GitHub-linked rooms may behave differently.
• Gitter was acquired by GitLab, and endpoint behavior may have changed. Confirm current behavior before production use.
• Public rooms are readable by anyone. Do not post credentials, secrets, or sensitive CI output to a public room.

Supported options compared

Option	Authentication	Best suited for	Key limitations
Incoming webhook	Webhook URL secret; no OAuth token	Simple fire-and-forget text notifications from scripts or CI	Cannot retrieve history, edit, or reply to messages; typically limited to simple text payloads
REST API	OAuth bearer token in the Authorization header	Markdown messages, programmatic control, and integrations that already manage tokens	Requires token storage, rotation, and handling 401 Unauthorized and 429 Too Many Requests responses

Trade-offs

The webhook is operationally simpler: copy a URL, POST JSON, and you are done. The trade-off is one-way delivery only. If a notification fails, the webhook gives no built-in mechanism to edit or retract the message from your integration.

The REST API costs more to operate. You must store a bearer token, refresh or rotate it, and handle HTTP errors. In return, you can send Markdown-formatted text and, depending on current Gitter behavior, interact with message history. Treat both the webhook URL and the OAuth token as secrets: anyone with either can post to the room.

Implementation: incoming webhook with curl

Run this from a terminal or CI job where the webhook URL is available as an environment variable or secret.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"text":"Build failed: main branch #482"}' \
  ''

• Where to run: any host with network access to Gitter, such as a CI runner or local shell.
• Permissions: access to the Gitter room settings page to copy the Incoming Webhook URL.
• Placeholder: replace <WEBHOOK_URL> with the URL copied from the room's Incoming Webhook settings.
• Expected check: the text message appears in the room timeline shortly after the request returns successfully.
• Risk: anyone who obtains the URL can post to the room. Rotate the URL immediately if it is leaked, and never post secrets to public rooms.

Implementation: REST API with curl

Run this from a terminal or CI job where a valid OAuth bearer token is available. Assumes the current Gitter REST API uses bearer-token authorization for chat messages; confirm the exact endpoint path in current documentation.

curl -X POST \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{"text":"**Deploy failed**\nEnvironment: production\nSee logs: https://ci.example.com/build/482"}' \
  ''

• Where to run: any host with network access to the Gitter REST API.
• Permissions: a Gitter or GitLab OAuth token with permission to send chat messages in the target room.
• Placeholders: replace <TOKEN> with your bearer token and <CHAT_MESSAGES_ENDPOINT> with the current endpoint for posting to the room, including the room ID.
• Expected checks: a successful response indicates the message was accepted; the message then appears in the room timeline. A 401 response means the token is expired or revoked; a 429 response means you are being rate limited.
• Risk: token leakage allows unauthorized posting. Store tokens in a secrets manager, rotate them on a schedule, and revoke tokens that are no longer needed.

Diagnostic decision flow

1. Do you need Markdown, message history, editing, or replies? Use the REST API.
2. Do you only need simple text notifications and want to avoid token management? Use the incoming webhook.
3. Are you already managing OAuth tokens for other services? The REST API may fit your existing pattern.
4. Is the room public? Avoid sensitive payloads regardless of which option you choose.

Validation steps

1. Open the Gitter room settings and copy the Incoming Webhook URL.
2. Run the webhook curl command with a test message such as {"text":"webhook validation"}.
3. Open the room in a browser and confirm the message appears in the timeline.
4. Delete the test message if Gitter's current interface supports deletion.
5. Repeat with the REST API using a token and room ID, then compare delivery latency, formatting, and error handling between the two methods.
6. Before production use, confirm that the webhook URL and REST endpoint still match current Gitter behavior after the GitLab acquisition.

Limitations

• Incoming webhooks are fire-and-forget. They do not support retrieving message history, editing messages, or replying to threads.
• The REST API requires active credential management. Lost or expired tokens break delivery until replaced.
• Exact rate limits, Markdown support in webhook payloads, and current endpoint availability should be verified against live Gitter documentation, because behavior may have changed after the GitLab acquisition.

Undoing a test message

Because posting a message changes room state, rollback means removing the test message. Open the room timeline, locate the test message, and delete it if the current Gitter UI supports message deletion. If deletion is not supported, the test message remains visible; avoid using sensitive text in validation. If you suspect a webhook URL or OAuth token was leaked, rotate the webhook URL in room settings or revoke the token immediately.