Configure and verify outbound webhooks

Outbound webhooks send monitor events to an HTTPS endpoint you control. They are useful for ticketing, incident automation, chat tools, and internal operations.

Availability and limits

Webhooks are disabled during a trial and become available on an active paid plan.

Plan	Endpoints	Delivery attempts per month
Starter	1	500
Plus	3	2,500
Pro	10	10,000

Every outbound HTTPS attempt uses the allowance, including retries, test deliveries, and manual redeliveries. The allowance resets at the start of each UTC month. Uptime Basics sends usage warnings at 80% and 90% when a verified account email is available.

Add an endpoint

1. Open Account > Integrations.
2. Select Add webhook.
3. Enter a descriptive name and an HTTPS destination on standard port 443.
4. Select the event types the endpoint should receive.
5. Choose All monitors or restrict the endpoint to selected monitors.
6. Add optional custom request headers if the destination requires them.
7. Create the endpoint and copy the signing secret immediately.
8. Select Send test, then review Deliveries.

Webhook destinations cannot contain URL credentials, use raw IP addresses, resolve to private or reserved networks, or redirect delivery to another URL. Uptime Basics resolves and validates the destination again during delivery and pins the validated address for that request.

Custom header values are encrypted and write-only. The account page shows their names, not their saved values. You can save a replacement set when needed. Transport and signing headers, including Host, Content-Length, Content-Type, User-Agent, and every Uptime-Basics-* header, are reserved and cannot be overridden. A webhook can have up to eight custom headers.

Event envelope

Every request uses envelope schema version 1:

{
  "schemaVersion": 1,
  "eventId": "evt_01example",
  "eventType": "incident.opened",
  "createdAt": "2026-08-01T16:00:00.000Z",
  "delivery": {
    "id": "del_01example",
    "attempt": 1,
    "redelivery": false,
    "redeliveryOf": null
  },
  "data": {
    "monitor": {
      "id": "monitor-id",
      "name": "Storefront",
      "url": "https://example.com",
      "status": "down",
      "previousStatus": "up",
      "checkedAt": "2026-08-01T16:00:00.000Z",
      "responseTimeMs": 5000,
      "httpStatus": 503,
      "failureCategory": "http_error",
      "failureReason": "The target returned an error response."
    },
    "incident": {
      "monitorId": "monitor-id",
      "startedAt": "2026-08-01T16:00:00.000Z",
      "resolvedAt": null,
      "type": "availability",
      "status": "open"
    }
  }
}

eventId identifies the event and remains unchanged across automatic retries and manual redelivery. delivery.id identifies one delivery sequence. A manual redelivery receives a new delivery ID, sets redelivery to true, and identifies the earlier delivery in redeliveryOf.

The data object contains a strict, tenant-safe set of fields. It never contains saved authentication values, custom request-header values, customer API tokens, billing data, or internal AWS identifiers.

Available event types are:

• monitor.status_changed
• incident.opened
• incident.resolved
• performance.slow
• performance.recovered
• ssl.expiring
• domain.expiring

Code should tolerate additional optional fields while using schemaVersion to detect a future breaking envelope version.

Verify the signature

Every request includes these protected headers:

Uptime-Basics-Event: incident.opened
Uptime-Basics-Event-Id: evt_01example
Uptime-Basics-Delivery: del_01example
Uptime-Basics-Signature: t=1785600000,v1=HEX_DIGEST

To verify the request:

1. Read the raw request body before parsing or reformatting JSON.
2. Extract t and every v1 value from Uptime-Basics-Signature.
3. Reject timestamps outside a short tolerance such as five minutes.
4. Compute HMAC-SHA256 over t + "." + raw_body using the signing secret.
5. Accept the request when one supplied v1 digest matches with a constant-time comparison.
6. Confirm the header event ID matches the body eventId.
7. Store the eventId and make event processing idempotent.

Do not log a signing secret or include it in a support request.

Rotate a signing secret

Select Rotate secret when a secret may be exposed or as part of routine credential maintenance. The new secret is shown once. The previous secret remains valid for 24 hours so you can deploy the new value without stopping delivery.

During that grace period, Uptime-Basics-Signature contains two v1 values. Configure your receiver to accept a match from either the current or previous secret, deploy the new secret, and remove the old secret after the grace period. Rotating again replaces the existing grace-period secret.

Response, retries, and redelivery

Return an HTTP status from 200 through 299 promptly after accepting an event. Put slow processing in your own queue after responding.

Uptime Basics makes no more than five attempts. Retriable failures use bounded delays of approximately 1, 5, 15, and 15 minutes. Timeouts, HTTP 408, 425, 429, and server errors are retried. Other client errors are recorded but are not automatically retried. Delivery requests time out after five seconds and do not follow redirects.

Open Deliveries beside an endpoint to review the event, attempt, response status, duration, delivery time, and safe failure category. Uptime Basics does not retain destination response bodies. You can manually redeliver a retained event from this history. Redelivery counts toward the monthly allowance, so the receiving system must deduplicate by eventId.

Endpoint health and suspension

Endpoint health shows whether recent delivery is healthy, warning, or suspended and includes the most recent successful delivery time.

• A successful delivery resets the consecutive-failure count.
• At seven consecutive failures, the endpoint enters warning state and Uptime Basics sends a warning when possible.
• At ten consecutive failures, the endpoint is suspended to prevent an endless delivery loop and additional cost.

Correct the destination and select Enable to resume a suspended endpoint. Send a test and confirm a successful delivery before relying on it for production automation.

Safe failure categories include HTTP 3xx, 4xx, and 5xx responses; timeout; DNS; TLS; connection; blocked target; transport error; and exhausted monthly allowance. Destination response bodies are never displayed or stored.

Troubleshooting checklist

• Confirm the URL uses HTTPS and port 443.
• Confirm DNS resolves publicly and does not return a private or reserved address.
• Return a 2xx response within five seconds.
• Do not redirect the webhook request.
• Verify the signature against the unmodified raw request body.
• During secret rotation, check every supplied v1 signature.
• Deduplicate work by eventId, not delivery.id.
• Review endpoint health and delivery-usage warnings under Account > Integrations.

Related articles

• Create and manage API tokens
• API scopes, limits, pagination, and safe automation