Pechkin

Pechkin is a small webhook → messenger proxy (currently Slack + Telegram). You define a config directory with bots, channels, message templates, and Pechkin turns incoming JSON POST requests into formatted messages.

gem install pechkin

The bundled config uses examples/bots/marvin.yml:

token_env: MARVIN_BOT_TOKEN
connector: slack

Set the env var before you run Pechkin:

export MARVIN_BOT_TOKEN=xoxb-your-actual-token-here

pechkin -c examples --check --list

Default bind is 127.0.0.1:9292:

pechkin -c examples

curl -X POST -H 'Content-Type: application/json' \
  --data '{"name":"all"}' \
  http://127.0.0.1:9292/my-org-random/hello

--send expects channel/message (no leading slash):

pechkin -c examples --send my-org-random/hello --data '{"name":"all"}' --preview

• Bot: how Pechkin authenticates to a messenger API (Slack/Telegram).
• Channel: where to deliver messages (one channel config can target multiple chat_ids).
• Message: how to render data into text + connector-specific payloads.
• View: ERB templates stored in views/.

Pechkin expects a directory layout:

.
├── bots/
│   └── marvin.yml
├── channels/
│   └── my-org-random/
│       ├── _channel.yml
│       └── hello.yml
└── views/
    └── hello.erb

Each bot file defines:

• token_env: env var name that contains the bot token
• connector: slack or telegram (also accepts tg)

Example:

# bots/marvin.yml
token_env: MARVIN_BOT_TOKEN
connector: slack

Views are ERB templates rendered with trim_mode: '-'.

Example:

Hello, <%= name %>!

Channel config defines:

• bot: which bot to use
• chat_ids: a string or list of destination chat IDs / channel IDs

Example:

# channels/my-org-random/_channel.yml
chat_ids: '#random'
bot: marvin

Message config defines:

• template: view path relative to views/ (e.g. hello.erb)
• variables: static variables merged into request data (request keys override)
• optional connector-specific fields like slack_attachments, telegram_parse_mode

Example:

# channels/my-org-random/hello.yml
template: hello.erb

For nested fields you can use { template: "..." } to render a template and replace that value. The object must contain only the template key.

Example:

template: gitlab-commit.erb
slack_attachments:
  - text:
      template: gitlab-commit-attachment.erb

Any string value in message config can substitute ${var} from the request JSON / variables.

Example:

slack_attachments:
  - title: Author
    value: "${author}"

You can control whether a message is sent using either allow or forbid rules (but not both).

• allow: message is sent if any rule matches (OR)
• forbid: message is sent if no rule matches

Example allow:

allow:
  - branch: 'master'

Example forbid:

forbid:
  - branch: 'testing'

• telegram_parse_mode: passed to Telegram parse_mode (default: HTML)

• slack_attachments: passed as Slack attachments to chat.postMessage. See Slack message attachments docs.

To send a direct message to a user by email:

1. Put 'email' in the channel’s chat_ids
2. Include an email field in the POST request JSON

Example channel config:

bot: marvin
chat_ids:
  - 'email'

Example request:

{
  "email": "user@example.com",
  "name": "all"
}

• Endpoint: POST /:channel/:message
• Body: JSON object
• Content-Type: application/json

Example:

curl -X POST -H 'Content-Type: application/json' \
  --data '{"name":"all"}' \
  http://127.0.0.1:9292/my-org-random/hello

If <config-dir>/pechkin.htpasswd exists (or you pass --auth-file), Pechkin will enforce HTTP Basic auth.

Create/update credentials:

# create/update examples/pechkin.htpasswd
pechkin -c examples --add-auth root:root123

Use a custom htpasswd file:

pechkin -c examples --add-auth root:root123 --auth-file /etc/config/pechkin.htpasswd
pechkin -c examples --auth-file /etc/config/pechkin.htpasswd

The repo ships docker/docker-compose.yml that mounts ../examples into the container.

cd docker
MARVIN_BOT_TOKEN=xoxb-your-actual-token-here docker compose up --build

Run:

pechkin --help

Common flows:

pechkin -c examples --check --list
pechkin -c examples --send my-org-random/hello --data '{"name":"all"}' --preview
pechkin -c examples --port 9292 --address 127.0.0.1

Pechkin exposes Prometheus metrics at:

curl http://127.0.0.1:9292/metrics

Includes:

• pechkin_start_time_seconds
• pechkin_version{version="..."}

• Bot token missing: ensure the env var named in token_env is exported before running Pechkin.\n+ Example: export MARVIN_BOT_TOKEN=...\n+- CLI preview/send endpoint format: --send uses channel/message (no leading /).\n+- Template prints nothing: use <%= ... %> (output) not <% ... %> (no output).

Pechkin is a postman from a Soviet animated film series.