Send a monitoring event to the system that handles it
An email can tell someone that a service needs attention. A webhook can also pass that event to your own receiver, where it can create a ticket, update an internal incident record or start a deliberately configured workflow.
MetriBeacon supports HTTP webhook notification destinations with JSON messages and HMAC-SHA256 signatures. This guide explains how to connect one, verify the request and handle delivery retries without creating duplicate work. The receiver's ticketing or workflow behaviour is your integration; creating a destination does not configure those actions automatically.
What is a monitoring webhook?
A monitoring webhook is an HTTP request sent when a configured notification is due. Your receiver accepts the event, checks its authenticity and decides what to do with it. It complements human-readable channels such as email and Telegram.
Keep three outcomes separate: the monitoring rule detects a condition, MetriBeacon hands a notification to the destination, and your system completes its own action. A successful handover does not prove that a ticket was created or a downstream workflow finished.
For example, a hypothetical receiver might open one internal ticket for a website incident and attach the recovery update to the same ticket. That is a design example, not a built-in promise about an external ticketing service.
Create the webhook destination in MetriBeacon
Follow the alarm and notification guide. Prepare a receiver you control at a permitted public HTTPS address. Use the final address directly; notification delivery does not follow redirects to find a different receiver.
- Open Alarms → Notifications and add a destination.
- Select the HTTP webhook channel and give it a recognisable name.
- Enter your receiver's public HTTPS address.
- Add an optional Bearer token if your receiver requires it.
- Create the destination and securely save the generated signing secret when shown.
- Configure that secret in the receiver, send a test and inspect both sides.
- Select the destination in the alarm rules that should use it.
The signing secret is displayed only once. It is separate from an optional Bearer token: the token authenticates according to your endpoint's policy, while the generated secret lets it verify the signed notification content. It is also separate from your monitoring data ingestion keys.
Review active destination selection when saving a rule. An active endpoint alone does not explain whether a particular rule is routed to it. Start with one test rule whose outcome you can inspect clearly.
Verify the original request bytes
MetriBeacon sends webhook notifications with HTTP POST and Content-Type: application/json. The request includes these headers:
| Header | Purpose |
|---|---|
X-MetriBeacon-Timestamp |
Signing timestamp expressed as Unix seconds |
X-MetriBeacon-Signature |
The v1= prefix followed by the HMAC-SHA256 digest in lowercase hexadecimal |
X-MetriBeacon-Delivery |
Stable notification identifier used for delivery deduplication |
The signature is calculated as:
v1=hex(HMAC-SHA256(signing_secret, timestamp + "." + raw_body))
Here, timestamp is the header's timestamp text and raw_body is the exact received body bytes. The signature covers the timestamp, a literal dot and those bytes. It does not cover JSON that your framework has parsed and serialized again.
Read and preserve the raw body before a JSON parser changes it. Whitespace, escaping and property order can change the bytes even if two JSON objects represent the same values. Verify with a constant-time comparison, validate the timestamp and apply a defined freshness window before acting on the message.
A signature check and freshness check serve different purposes. A previously valid captured request can still have a correct signature; the receiver must also reject stale requests and remember work it already accepted. Keep signing secrets and authorization values out of request logs and public error messages.
Separate a notification from its individual events
The JSON notification includes a schema_version, notification_id, type and an entries array. Entries contain incident and event identifiers and relevant rule information. A notification can carry several entries, so do not process only the first array element.
Use notification_id as the stable identity of a delivery. Use an entry's incident_id to correlate updates belonging to the same incident, and retain its event_id when tracking individual events. Those identifiers answer different questions. Deduplicate using the signed body’s notification_id and check that X-MetriBeacon-Delivery agrees with it; that delivery header itself is not part of the signed bytes.
For the illustrative ticket integration, duplicate delivery should not create a second ticket. A later recovery notification has its own delivery identity but can refer to the existing incident. Keep that correlation in your application rather than treating every received message as a new problem.
Validate the supported schema and event type before using fields. A test notification is not evidence that a real monitor failed. Webhook timestamps stay in UTC; convert them for display without changing their meaning.
Accept durably, then do longer work
A practical receiver first authenticates and validates the request. It then records the delivery identity and the intended work durably, as one operation, before returning a successful HTTP response. A worker can perform the slower ticket or workflow action afterward.
That is a receiver design pattern, not a queue that MetriBeacon installs in your application. Use it to avoid confirming a message that only reached temporary process memory. When a duplicate accepted delivery arrives, recognize it and avoid repeating its business action.
MetriBeacon treats a successful 2xx webhook response as handover to the endpoint. It cannot see whether your own queue subsequently stalled. Monitor the receiver's processing state separately if that outcome matters.
If processing order matters, use the incident and event information to reconcile updates. Do not make arrival order your only record of the incident's state.
Expect retries without assuming exactly-once delivery
A network connection can fail after your receiver accepted a notification but before MetriBeacon receives its response. A later attempt can therefore deliver the same notification again.
Retries use a fresh signing timestamp while keeping the same notification identifier. Do not deduplicate by timestamp or signature: those values may change between attempts. Persist accepted identifiers with the work they represent.
Temporary failures can lead to retries with backoff. Permanent target or configuration errors need correction. Review the actual result in the incident and delivery history instead of assuming every failure will retry indefinitely.
All notification channels share delivery allowances. A webhook does not bypass account limits, muted delivery or relevant maintenance settings. The usage overview and delivery history help distinguish a rule problem from a suppressed or failed handover.
Test the integration as a complete path
Start with a non-destructive receiver action, such as creating an internal test record. Send MetriBeacon's destination test and confirm signature verification, accepted identity and the downstream result. Test messages share the account's limit of ten per hour across channels.
Then exercise a controlled condition on your own test monitor and verify the incident notification and recovery. Use a website monitor, a job rule or a log alert that fits the signal you actually need.
In your receiver tests, also cover an altered body, an invalid signature, a stale request and a duplicate valid delivery. Confirm that the duplicate does not repeat the intended action. Those checks protect different parts of the integration.
A private webhook integration and a public status-page subscription are separate setups. Use an explicitly published status page when visitors need reviewed service information; do not forward private alarm payloads into public updates automatically.
Frequently asked questions about monitoring webhooks
Does a webhook replace email or Telegram alerts?
No. It is another destination for configured rules. Keep the human notification channels that fit your response process.
Is the Bearer token the webhook signing secret?
No. The optional token and generated HMAC secret have different purposes. Configure and protect each value separately where used.
Can the same notification arrive more than once?
Yes. An uncertain response can lead to another delivery attempt. Use the stable notification identifier and durable deduplication rather than assuming exactly-once effects.
Is webhook alerting free with MetriBeacon?
MetriBeacon is free within its documented technical quotas. Delivery budgets still apply, and an external receiver or workflow provider may have its own charges.
Start with one receiver and one useful action
Create a free MetriBeacon account, prepare a verified receiver implementation and connect one webhook destination. Test authentication, duplicate handling and the downstream result before expanding routing. The Website/API template below creates a complementary HTTP monitor; configure webhook delivery separately under Alarms → Notifications.
