Hermes webhooks

Give Hermes a secure public webhook URL without exposing its Agent API.

Hermes receives webhook events on port 8644, which Pusk keeps credential-protected by default. This page covers the Pusk-specific step: giving that port a stable public URL without exposing the Agent API on port 3737.

For Hermes route configuration, payload templates, delivery targets, and supported signatures, use the Hermes webhook guide.

1. Create the Hermes subscription

Open the Hermes dashboard on port 9119 with a signed URL, then select Webhooks. Enable the receiver if needed and create a subscription. Pusk manages the Hermes gateway restart.

Hermes shows a local URL and a signing secret when the subscription is created:

http://localhost:8644/webhooks/call-ended

Copy the secret when Hermes shows it. Keep the /webhooks/call-ended path; replace only the local origin below.

2. Give port 8644 a named URL

Add a prefix to make the hostname readable and stable:

curl -X POST https://api.pusk.ai/v1/instances/ab12cd34ef/public-ports \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "port": 8644, "prefix": "webhooks" }'

{
  "port": 8644,
  "url": "https://webhooks-ab12cd34ef.pusk.app",
  "domain_urls": [],
  "prefix": "webhooks",
  "created": 1783900800
}

A prefix produces {prefix}-{instanceId}.pusk.app; it does not claim a global bare hostname. Omit prefix if you prefer a random, unguessable hostname. See Public ports for creation-time configuration, rotation, and limits.

3. Replace the local origin

Combine the returned Pusk origin with the path Hermes showed:

https://webhooks-ab12cd34ef.pusk.app/webhooks/call-ended

Configure the external service with this URL and the Hermes signing secret. The public URL supplies reachability; Hermes still authenticates the delivery using the signature rules in its documentation.

Test the subscription locally from the instance terminal, then use the provider's test-delivery feature:

hermes webhook test call-ended