Using Webhooks in the UI

Use the Webhooks section to manage endpoint configuration and subscriptions without calling webhook API routes directly.

Create an Event Webhook

1. Open Webhooks.

2. Select Add Webhook.

3. In the creation modal, choose Event as the webhook type.

4. Enter endpoint details:

   • name
   • url

   For local testing, you may use an HTTPS tunnel such as https://<your-subdomain>.ngrok-free.app/webhook.

5. Enter subscription details:

   • contract
   • topic0
   • Optional: enable Decode Events to include decoded event data in deliveries

6. Select Create Webhook.

7. Copy and securely store the signing key immediately.

8. Acknowledge the one-time signing key modal to continue.

Create an Address Webhook

1. Open Webhooks.
2. Select Add Webhook.
3. In the creation modal, choose Address as the webhook type.
4. Enter endpoint details:
   • name
   • url
5. Add one or more EVM addresses to monitor.
6. Select Create Webhook.
7. Copy and securely store the signing key immediately.
8. Acknowledge the one-time signing key modal to continue.

Open Webhook Details

From the webhook table:

1. Select the webhook row you want to inspect.

The admin UI opens a full webhook details page. The page header contains the available actions for that webhook:

• Edit
• Rotate Signing Key
• Pause or Activate
• Delete

The details page displays:

General Information

• Created at
• Type
• Status — Active, Paused, or Suspended (see Suspended Webhooks)
• Webhook ID

Destination

• Destination URL

Event Webhooks

• Contract address
• Event topic (topic0)
• Decode events status

Address Webhooks

• Monitored addresses, loaded dynamically from the webhook service

Pause or Activate a Webhook

You can temporarily stop deliveries without deleting the webhook.

From the webhook details page:

1. Select Pause if the webhook is active, or Activate if it is paused or suspended.

When paused:

• The webhook remains configured.
• No new deliveries are sent.
• The subscription remains intact.

The webhook status is visible in the details page and in the webhooks table.

Suspended Webhooks

The webhook service can suspend a webhook when it encounters a persistent delivery problem. A suspended webhook differs from a paused one: the service disabled it, not the admin.

The details page shows a plain-language explanation below the status badge. Common suspension reasons:

• Repeated delivery failures — the endpoint could not be reached after multiple attempts.
• HTTP 410 Gone — the endpoint returned 410, signaling that it no longer accepts deliveries.
• Permission revoked — the webhook owner lost access to the chain.

To resume deliveries:

1. Resolve the underlying problem (restore endpoint availability, handle the 410 response, or restore chain access).
2. Select Activate on the webhook details page.

Edit a Webhook

From the webhook details page:

1. Select Edit.
2. Update the mutable fields:
   • name
   • url
   • decode_events for event webhooks
3. Select Save Changes.

The UI currently shows monitored addresses in read-only form for address webhooks.

Rotate a Signing Key

From the webhook details page:

1. Select Rotate Signing Key.
2. In the rotation modal, review retire_after_secs.
   • The field is required.
   • The default value is 86400 seconds.
3. Select Rotate.
4. In the confirmation dialog, type Rotate signing key.
5. Confirm the rotation.
6. Copy the new signing key from the one-time modal.
7. Acknowledge the modal to continue.

During the overlap window, your verifier must accept signatures generated by both the old and new keys. See Rotating Signing Keys for the API details and overlap guidance.

Delete a Webhook

From the webhook details page:

1. Select Delete.
2. In the confirmation dialog, type Delete webhook.
3. Confirm deletion.

Deleting a webhook permanently removes:

• The endpoint
• Its associated subscription

This action cannot be undone.