Skip to content

Using webhooks

A webhook is a URL that posts messages into one guild channel. It needs no bot account, no gateway connection and no Authorization header: the secret token is part of the URL. Webhooks are the simplest way to push notifications (build results, alerts, feeds) into TEBHOS.

Bot Webhook
Separate account Yes, a bot user No
Receives events Yes, over the gateway No
Sends messages To any channel it can access Only to its own channel
Credential Bot token in the Authorization header Token in the URL
Can be used from Your server Anything that can send an HTTP POST

Paths are relative to https://tebhos.com/api/v1. The full reference is Webhooks.

Create a webhook

In the TEBHOS app, open the channel's settings and create a webhook in its Webhooks section, then copy its URL. Through the API:

POST /channels/{channel_id}/webhooks

Requires the Manage Webhooks permission (and View Channel) in that channel. Works with a user session or a bot token. Only guild channels can have webhooks. Rate limit: 10 per minute per channel. A channel can have at most 15 webhooks and a guild at most 1000.

Field Type Description
name string Default display name, 1–80 characters
avatar? ?string Default avatar as a data URI (data:image/png;base64,...) 
curl -X POST https://tebhos.com/api/v1/channels/1290849012346880000/webhooks \
  -H "Authorization: Bot $TEBHOS_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI"}'

{
  "id": "1290860512238080000",
  "guild_id": "1290848871133052928",
  "channel_id": "1290849012346880000",
  "name": "CI",
  "avatar": null,
  "token": "fS3kq...9Zp"
}

The webhook URL is https://tebhos.com/api/v1/webhooks/{id}/{token}.

The webhook URL is a secret

Anyone with the URL can post into the channel. Store it like a password. If it leaks, delete the webhook and create a new one.

Execute a webhook

POST /webhooks/{webhook_id}/{webhook_token}

Posts a message. No Authorization header. Rate limit: 60 per minute per webhook.

Field Type Description
content? string Message text, up to 4000 characters
embeds? array Up to 10 rich embeds: title, description, url, color, timestamp, author, image, thumbnail, footer, fields. See Embed limits
username? string Overrides the webhook's display name for this message, 1–80 characters
allowed_mentions? object parse (a list of "users", "everyone") and users (a list of user IDs) limit which mentions notify people. When omitted, nobody is notified ({"parse": []})
flags? integer Message flags

content or embeds is required; a message with neither returns 400.

Query Type Description
wait? boolean true returns 200 with the created message object. Default: 204 with no body 
curl -X POST "https://tebhos.com/api/v1/webhooks/1290860512238080000/fS3kq...9Zp?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"username": "CI", "content": "Build #812 passed", "embeds": [{"title": "main", "description": "All 214 tests green", "color": 3066993}]}'

Not supported on TEBHOS

avatar_url, attachments, message_reference, sticker_ids, nonce and tts are accepted for compatibility but ignored: a webhook message always uses the webhook's stored avatar, carries no files or stickers, and is never a reply.

Compatible formats

Services that only speak another webhook format can post to the same webhook through a format-specific path:

Path Accepts
POST /webhooks/{webhook_id}/{webhook_token}/github GitHub webhook deliveries
POST /webhooks/{webhook_id}/{webhook_token}/slack The common incoming-webhook JSON format (text, username, attachments with title, text, color and fields). Answers ok on success
POST /webhooks/{webhook_id}/{webhook_token}/instatus Instatus status-page notifications

Edit or delete a webhook message

With the same token you can manage messages the webhook posted:

Action Endpoint
Get GET /webhooks/{webhook_id}/{webhook_token}/messages/{message_id}
Edit PATCH /webhooks/{webhook_id}/{webhook_token}/messages/{message_id}
Delete DELETE /webhooks/{webhook_id}/{webhook_token}/messages/{message_id}

Manage the webhook itself

Action Endpoint
Read it without auth GET /webhooks/{webhook_id}/{webhook_token}
Rename, change avatar PATCH /webhooks/{webhook_id}/{webhook_token}
Delete it DELETE /webhooks/{webhook_id}/{webhook_token}
List a channel's webhooks GET /channels/{channel_id}/webhooks (needs Manage Webhooks)

Choose a bot when you need to react to what happens in TEBHOS, and a webhook when you only need to post.