Receive your first webhook

This walkthrough assumes you have deployed wiretap-relay at a public HTTPS address such as https://relay.example.com.

1. Register this desktop

Registration creates one desktop identity. Run it once and save the returned client credentials:

wiretap relay \
  --url https://relay.example.com \
  --admin-token YOUR_ADMIN_TOKEN \
  register --name laptop --save

The admin token is needed for registration, but not for ordinary project changes. Do not place it in a URL, shell history, or committed config file.

2. Claim a project path

Use the saved desktop credentials to add a project:

wiretap relay --url https://relay.example.com projects add project-a

project-a becomes the first segment of the public webhook URL. A project currently has one owning desktop identity.

3. Configure the outbound tunnel

Open the configuration file created by wiretap config init and set:

relay:
  url: wss://relay.example.com/tunnel

The configured value is a WebSocket URL. Relay administration commands use the HTTPS base URL passed with --url.

4. Connect Wiretap

Start the desktop or terminal UI:

wiretap gui

The status area should show a connected relay and project-a. The desktop dials outward, so it needs no public IP or inbound firewall rule.

5. Send a webhook

From any machine that can reach the relay:

curl -X POST https://relay.example.com/project-a/orders/created \
  -H 'Content-Type: application/json' \
  -H 'X-Test-Event: order.created' \
  -d '{"order_id":"test-123"}'

Open Webhooks and select the delivery. Wiretap preserves everything after the project segment, so the recorded path is /orders/created.

6. Replay it locally

In the webhook detail, choose Replay, enter your local endpoint such as http://127.0.0.1:8080/webhooks, and send it again. You can set relay.forward_url to forward every arriving webhook automatically.

For adding, removing, or moving project ownership later, see Manage the relay.