Notifications

oec.sh can notify your team whenever something important happens — a deployment completes, an automation rule fails, an environment is created. Two delivery channels are available and can be used together.

Channel	Best for
Outgoing Webhooks	Slack, Teams, Discord, CI/CD pipelines, custom automation
Email Notifications	Team inboxes, on-call distribution lists, management updates

Both channels share the same set of events and can be scoped to a specific project or applied org-wide.

Available Events

Event	What happened
`deploy.started`	A deployment task began executing
`deploy.completed`	A deployment finished successfully
`deploy.failed`	A deployment finished with an error
`deploy.cancelled`	A deployment was cancelled
`environment.created`	A new environment was provisioned
`environment.deleted`	An environment was deleted
`environment.status_changed`	An environment's run status changed
`automation_rule.triggered`	An automation rule matched its trigger and started
`automation_rule.completed`	An automation rule ran all actions successfully
`automation_rule.failed`	An automation rule failed during execution

Outgoing Webhooks

Webhooks deliver an HTTP POST to your endpoint every time a subscribed event fires. oec.sh signs each delivery with HMAC-SHA256 so your server can verify the payload is genuine.

Setting up a webhook

Go to Settings → Webhooks in your organisation dashboard.

Choose a destination

Enter the URL of your endpoint. It must use HTTPS. Private IP addresses and loopback addresses are rejected.

Choose a format that matches your destination:

Format	Use when
Raw (default)	Custom server, CI script, or any automation that reads JSON
Slack	Slack Incoming Webhook URL — delivers a Block Kit message
Teams	Microsoft Teams Incoming Webhook — delivers an Adaptive Card
Discord	Discord channel webhook — delivers a rich embed

Subscribe to events

Select the events you care about. You can subscribe to up to 10 events per webhook. Use project scoping if you only want events from a specific project.

Save the signing secret

After you create the webhook, the dashboard shows a whsec_... signing secret once. Copy it to a safe location — it cannot be retrieved again. If you lose it, rotate it from the webhook detail page.

Test the connection

Click Send test to fire a ping event to your endpoint. The dashboard shows the HTTP response code and round-trip time.

Verifying signatures

Every raw delivery includes an X-OEC-Signature header:

X-OEC-Signature: sha256=<hex_digest>

import hashlib, hmac
 
def verify(raw_body: bytes, header: str, secret: str) -> bool:
    expected = header.removeprefix("sha256=")
    computed = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, expected)

⚠️

Always use timing-safe comparison. Never use == — it is vulnerable to timing attacks.

Platform formats (slack, teams, discord) do not send an X-OEC-Signature header — those services authenticate via their own URL tokens.

Reliability

Your endpoint must respond with 2xx within 10 seconds
Failed deliveries are retried up to 5 times with exponential backoff (30s → 5min → 30min → 2h)
After 10 consecutive failures, the webhook is automatically paused
A delivery log showing every attempt is available on the webhook detail page

Limits

Up to 100 webhooks per organisation
Up to 10 events per webhook
Webhook mutations are rate-limited to 10 per minute per API key

Email Notification Channels

Email channels send formatted HTML emails to a list of recipients when subscribed events fire. They are delivered asynchronously via a background queue and do not affect the operation that triggered them.

Setting up an email channel

Go to Settings → Email Alerts in your organisation dashboard.

Add recipients

Enter one or more email addresses, separated by commas or new lines. Up to 20 recipients per channel.

Subscribe to events

Choose up to 10 events to listen for. Optionally scope the channel to a single project — channels without a project scope receive all matching org-level events.

Add a description

A short label helps distinguish channels when you have more than one (e.g. "Deploy failures → DevOps team", "All events → Management").

Send a test email

Click Send test email to confirm delivery is working. A sample notification arrives at all recipients within a few seconds.

Email format

Notifications arrive as clean HTML emails. Each email includes:

A colour-coded header reflecting the event type (green for success, red for failure, blue for informational)
Key details extracted from the event (rule name, action type, branch, actor, environment name)
A link to manage notification settings

Limits

Up to 10 email channels per organisation
Up to 20 recipients per channel
Up to 10 events per channel

Project Scoping

Both webhooks and email channels can be scoped to a specific project. A project-scoped channel only fires when the event is associated with an environment in that project.

If you leave the project field empty, the channel receives all matching events across your organisation.

Automation Rules Integration

When an automation rule completes or fails, oec.sh fires automation_rule.completed or automation_rule.failed. These events include:

Field	Description
`rule_name`	The human-readable name of the automation rule
`action_type`	What the rule did (e.g. `deploy_latest`, `restart`)
`trigger_type`	What caused the rule to fire (e.g. `push`, `schedule`)
`branch`	The branch that triggered the rule, if applicable
`actor`	Who or what triggered the rule
`error`	Error message, for `automation_rule.failed` events

The automation rules pipeline overview in your project settings shows small indicator pills for all notification channels subscribed to that rule's events — green for webhooks, blue for email channels.

Permissions

Viewing notification settings requires the Viewer role or higher.

Creating, editing, and deleting notification channels requires the Admin role or higher.

Alerts Overview