Skip to content
NimbusNexus

Endpoint verification

Verification proves that the URL behind an endpoint is yours and is ready for webhooks. We send it one signed challenge; it passes by echoing the challenge back. Until it passes, a workspace that requires verification delivers nothing to it — which catches a mistyped URL or a half-built receiver before real events pile up in the dead-letter queue, and keeps anyone from pointing our deliveries at a server that never asked for them.

The challenge

Starting a verification sends one POST to the endpoint's URL, signed with the endpoint's secret exactly like a delivery (the same X-Webhook-Signature and X-Webhook-Timestamp, your endpoint's custom headers, and X-Webhook-Event-Type: webhook.verify):

JSON
{"type": "webhook.verify", "data": {"endpoint_id": "ep_3f9a…", "challenge": "Xb9kQ2…"}}

The endpoint passes when it answers 2xx with the challenge value anywhere in the response body. A 2xx without the token fails with challenge_not_echoed; anything else fails like a delivery would.

Answering it

Check the signature as you do for every delivery, then return the challenge:

event = json.loads(raw_body)                       # after the signature check
if event["type"] == "webhook.verify":
    return Response(event["data"]["challenge"], status=200)

No REST example here; showing Python.

Running it

In the console, open the endpoint's menu on the Endpoints page and choose Verify. Through the API:

Shell
curl -sX POST https://webhooks.nimbusnexus.net/v1/endpoints/ep_3f9a…/verify \
  -H "Authorization: Bearer $ADMIN_KEY"
JSON
{ "verified": true, "challenge_echoed": true, "status_code": 200, "error": null, "duration_ms": 142, "failure_reason": null }

An endpoint stays verified until its URL changes; a new URL has to verify again.

When it is required

Verification is required for an endpoint when any of these is on:

  • the workspace switch — Settings → Endpoint verification in the console, or PATCH /v1/workspace with {"require_endpoint_verification": true};
  • the project switch — PUT /v1/verification-policy?project_id=… with {"required": true}, for a project that needs it when others do not;
  • your plan, where the plan requires it. The console then shows the switch locked on.

GET /v1/verification-policy returns the rule as delivery applies it (required), alongside the two switches.

What an unverified endpoint misses

When verification is required, an unverified endpoint is left out when an event fans out: the publish response counts it in skipped_unverified, the console marks the endpoint gated, and no delivery is created for it — so nothing waits to be sent once it verifies. Publish or replay again after it passes. Deliveries created before the requirement was switched on keep retrying.

Receivers that cannot answer

Some receivers accept any POST but never echo a body you choose — Slack's incoming webhooks and Zapier's catch hooks among them. They cannot pass verification. Where your plan lets you, leave verification off for the project that delivers to them; otherwise put a small relay of your own in front that answers the challenge.

What's next

Edit this page on GitHub