Task Ember provides webhook endpoints for receiving alerts from external services.
Send an alert to the Inbox via webhook.
Endpoint:
POST https://apim-taskember.azure-api.net/webhook/{databaseId}/{webhookId}
Headers:
| Header | Required | Description |
|---|---|---|
x-api-key | Yes | Your webhook API key |
Content-Type | Yes | Must be application/json |
x-taskember-signature | Yes | sha256=<hex> HMAC of the request (see Signing requests) |
x-taskember-timestamp | Yes | Unix time in seconds when the request was signed |
x-idempotency-key | Recommended | Unique id for this delivery. It is signed, and duplicates are dropped by it. Always send it; x-event-id is used only when it is absent |
Webhooks created in the portal require a signature. Compute an HMAC-SHA256 over
{timestamp}\n{deliveryId}\n{rawBody}
that is, the timestamp, a newline, the delivery id, a newline, then the exact
bytes of the body you send (not a re-serialised copy). Key it with the
webhook's signing secret and send it hex-encoded as
x-taskember-signature: sha256=<hex> alongside the x-taskember-timestamp you
signed with. The API key still goes in x-api-key, but it is never the signing
key.
The delivery id is the trimmed value of x-idempotency-key, or of
x-event-id when that is absent. With neither it is empty, so the signed
string starts {timestamp}\n\n. x-request-id is never used, because proxies
can add or rewrite it. A delivery id containing a line break is rejected.
Always send x-idempotency-key with a new unique value (such as a UUID) for
each delivery, and reuse it only when retrying the same one: Task Ember drops
duplicate deliveries by this id.
A request is rejected when the signature is missing, does not match, or the timestamp is more than 300 seconds away from the receiver's clock. Signing can't be turned off. The one exception is a webhook made for an uptime heartbeat monitor, which accepts requests on the API key alone, but a signature that is present and wrong is still rejected.
The signing secret is shown once, when the webhook is created. Rotate signing secret on the webhook card replaces it, and the old secret stops working immediately.
Webhooks without a signing secret: webhooks created before signing secrets
existed are verified with the older scheme until their owner clicks Generate
signing secret: an HMAC-SHA256 over {timestamp}.{rawBody}, keyed with the
API key. Generate a signing secret to move off it, since the API key travels
with every request.
TIMESTAMP=$(date +%s)
DELIVERY_ID=$(uuidgen)
BODY='{"title":"Server CPU High","severity":"warning"}'
SIGNATURE=$(printf '%s\n%s\n%s' "$TIMESTAMP" "$DELIVERY_ID" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex \
| sed 's/^.* //')
curl -X POST "$WEBHOOK_URL" \
-H "x-api-key: $API_KEY" \
-H "x-idempotency-key: $DELIVERY_ID" \
-H "x-taskember-timestamp: $TIMESTAMP" \
-H "x-taskember-signature: sha256=$SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
Request Body:
{
"title": "Alert title",
"severity": "critical",
"message": "Optional detailed description",
"source": "Your service name",
"metadata": {
"key": "value"
}
}
Fields:
| Field | Type | Required | Description |
|---|---|---|---|
title | string | No | Alert title, up to 500 characters (defaults to "Webhook Alert") |
severity | string | No | One of critical, warning, info (defaults to info) |
message | string | No |
Any other top-level field is rejected.
Response:
{
"success": true,
"alertId": "wh-abc123-def456"
}
Error Responses:
| Status | Description |
|---|---|
| 400 | Invalid JSON body, or a body that breaks the field rules above |
| 401 | API key missing or invalid (a disabled webhook's key is suspended), signature missing or invalid (for example signed with the API key instead of the signing secret), or timestamp outside the 300 second window |
| 403 | Webhook is disabled, or the API key belongs to a different webhook |
| 404 | Webhook not found |
| 413 | Body larger than 1 MB |
| 429 | Rate limit exceeded (see Rate Limits) |
| 500 | Internal server error |
WEBHOOK_URL="https://apim-taskember.azure-api.net/webhook/YOUR_DATABASE_ID/YOUR_WEBHOOK_ID"
API_KEY="YOUR_API_KEY"
SIGNING_SECRET="YOUR_SIGNING_SECRET"
TIMESTAMP=$(date +%s)
DELIVERY_ID=$(uuidgen)
BODY='{"title":"Server CPU High","severity":"warning","message":"CPU usage at 95% on prod-web-01","source":"monitoring-agent","metadata":{"host":"prod-web-01","region":"uk-south","cpu_percent":"95"}}'
SIGNATURE=$(printf '%s\n%s\n%s' "$TIMESTAMP" "$DELIVERY_ID" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex \
| sed 's/^.* //')
curl -X POST "$WEBHOOK_URL" \
-H "x-api-key: $API_KEY" \
-H "x-idempotency-key: $DELIVERY_ID" \
-H "x-taskember-timestamp: $TIMESTAMP" \
-H "x-taskember-signature: sha256=$SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
$apiKey = "YOUR_API_KEY"
$signingSecret = "YOUR_SIGNING_SECRET"
$body = @{
title = "Backup Complete"
severity = "info"
message = "Nightly backup finished successfully"
source = "backup-service"
metadata = @{
database = "prod-db-01"
duration = "12 minutes"
size = "2.4 GB"
}
} | ConvertTo-Json -Compress
$timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
# Always send a delivery id: it is signed, and retries of the same delivery reuse it
$deliveryId = [guid]::NewGuid().ToString()
$hmac = [System.Security.Cryptography.HMACSHA256]::new([Text.Encoding]::UTF8.GetBytes($signingSecret))
$hash = $hmac.ComputeHash([Text.Encoding]::UTF8.GetBytes("$timestamp`n$deliveryId`n$body"))
$signature = -join ($hash | ForEach-Object { $_.ToString("x2") })
Invoke-RestMethod `
-Uri "https://apim-taskember.azure-api.net/webhook/YOUR_DATABASE_ID/YOUR_WEBHOOK_ID" `
-Method Post `
-Headers @{
"x-api-key" = $apiKey
"x-idempotency-key" = $deliveryId
"x-taskember-timestamp" = $timestamp
"x-taskember-signature" = "sha256=$signature"
} `
-ContentType "application/json" `
-Body $body
import hashlib
import hmac
import json
import time
import uuid
import requests
body = json.dumps({
"title": "Deployment Failed",
"severity": "critical",
"message": "Production deployment rolled back due to health check failure",
"source": "ci-pipeline",
"metadata": {
"pipeline": "main-deploy",
"commit": "abc1234",
"environment": "production",
},
}).encode()
timestamp = str(int(time.time()))
delivery_id = str(uuid.uuid4())
signature = hmac.new(
b"YOUR_SIGNING_SECRET",
f"{timestamp}\n{delivery_id}\n".encode() + body,
hashlib.sha256,
).hexdigest()
response = requests.post(
"https://apim-taskember.azure-api.net/webhook/YOUR_DATABASE_ID/YOUR_WEBHOOK_ID",
headers={
"x-api-key": "YOUR_API_KEY",
"x-idempotency-key": delivery_id,
"x-taskember-timestamp": timestamp,
"x-taskember-signature": f"sha256={signature}",
"Content-Type": "application/json",
},
data=body,
)
print(response.json())
import { createHmac, randomUUID } from "node:crypto";
const body = JSON.stringify({
title: "New User Signup",
severity: "info",
message: "[email protected] signed up",
source: "auth-service",
metadata: {
email: "[email protected]",
plan: "pro",
},
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const deliveryId = randomUUID();
const signature = createHmac("sha256", "YOUR_SIGNING_SECRET")
.update(`${timestamp}\n${deliveryId}\n${body}`)
.digest("hex");
const response = await fetch(
"https://apim-taskember.azure-api.net/webhook/YOUR_DATABASE_ID/YOUR_WEBHOOK_ID",
{
method: "POST",
headers: {
"x-api-key": "YOUR_API_KEY",
"x-idempotency-key": deliveryId,
"x-taskember-timestamp": timestamp,
"x-taskember-signature": `sha256=${signature}`,
"Content-Type": "application/json",
},
body,
}
);
const data = await response.json();
console.log(data);
Any tool that can run a script can sign its requests, like the GitHub Actions step below.
Tools that can only send a fixed URL and headers, such as Grafana alerting and Azure DevOps service hooks, can't sign requests, so they can't send to a webhook directly. Point them at a small relay you run instead (a script, scheduled job or serverless function) that builds the alert body and signs it. A workflow's HTTP Request step can't sign either, so it can't send to another webhook.
Add a step to your workflow to notify Task Ember on deployment:
- name: Notify Task Ember
if: always()
run: |
BODY='{"title":"Deploy ${{ job.status }}","severity":"${{ job.status == 'success' && 'info' || 'critical' }}","source":"github-actions","metadata":{"repo":"${{ github.repository }}","commit":"${{ github.sha }}"}}'
TIMESTAMP=$(date +%s)
DELIVERY_ID=$(cat /proc/sys/kernel/random/uuid)
SIGNATURE=$(printf '%s\n%s\n%s' "$TIMESTAMP" "$DELIVERY_ID" "$BODY" \
| openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex \
| sed 's/^.* //')
curl -X POST "$WEBHOOK_URL" \
-H "x-api-key: $API_KEY" \
-H "x-idempotency-key: $DELIVERY_ID" \
-H "x-taskember-timestamp: $TIMESTAMP" \
-H "x-taskember-signature: sha256=$SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
env:
WEBHOOK_URL: ${{ secrets.TASKEMBER_WEBHOOK_URL }}
API_KEY: ${{ secrets.TASKEMBER_API_KEY }}
SIGNING_SECRET: ${{ secrets.TASKEMBER_SIGNING_SECRET }}
Webhook requests are rate-limited through Azure API Management. If you exceed the limit, you will receive a 429 Too Many Requests response.
title values so alerts are easy to scan in the Inboxseverity appropriately - reserve critical for genuine outagesmetadata for troubleshooting (host names, error codes, etc.)source field so you can filter alerts by service| Detailed alert description, shown under the title in the inbox, up to 10,000 characters |
source | string | No | Name of the service sending the alert, up to 200 characters |
metadata | object | No | Up to 50 key-value pairs for additional context. Values must be strings of up to 2,000 characters; keys are up to 64 characters of letters, digits, _, ., : or - |