WebhookOps

Getting started

WebhookOps Quickstart: Receive and Forward Your First Webhook

Create a public webhook endpoint, forward requests safely to localhost, or deliver them to your Test and Production destination URLs.

4 min read

Step 1

Create an endpoint

Open the Console, give the endpoint a recognizable name, and create its receiving URL. Copy that URL into the webhook provider you are connecting.

WebhookOps Console create endpoint form

Step 2

Forward to your local handler

Run npx webhookops dev <port>, using the port your local service listens on. The CLI creates an outbound relay, so your machine does not need a public inbound port.

WebhookOps Console local forwarding instructions

Step 3

Configure a destination domain

Save Test and Production destination URLs in Settings, then select the environment that should receive new live requests. Each request remains available in Events with its delivery result.

WebhookOps Console Test and Production destination settings

Choose the forwarding mode for the work you are doing

WebhookOps receives the public request once and stores the original method, path, headers, and body. You can then forward new requests through the CLI to localhost while developing, or forward them to a destination domain configured for Test or Production.

Local forwarding and destination delivery solve different needs. Use the local relay while changing a handler on your machine. Use a destination URL when you need a controlled delivery to a staging or production service.

Verify each delivery in Events

After sending a test request or receiving a live webhook, open Events for the endpoint. Review the incoming request and its delivery result before changing configuration or debugging downstream behavior.

Make downstream handling idempotent

For a cloud delivery to a configured Test or Production destination, WebhookOps removes any inbound X-WebhookOps-* headers and writes its own trusted delivery metadata. This prevents a provider or another caller from impersonating a WebhookOps delivery.

Use X-WebhookOps-Event-Id as the durable event correlation key in your handler. A retry of the same delivery keeps its Event ID and Delivery ID while X-WebhookOps-Attempt increases. A manual replay keeps the original Event ID and additionally includes X-WebhookOps-Replay: true and X-WebhookOps-Replay-Id.

This supports safe deduplication; it is not an exactly-once guarantee. Your handler should record the Event ID before performing an irreversible action. Local CLI forwarding has its own development metadata and is not a substitute for this cloud-delivery contract.

  • X-WebhookOps-Event-Id: the captured event UUID.
  • X-WebhookOps-Delivery-Id: the current delivery UUID.
  • X-WebhookOps-Attempt: a positive attempt number for that delivery.
  • X-WebhookOps-Forwarded-At: the UTC time WebhookOps created the outbound request.