Setup

Create a webhook endpoint, pass URL verification, subscribe to the events you need, and securely store the one-time secret used to sign every delivery.

Creating an endpoint

Go to Project → Webhooks → Add endpoint.

Enter your publicly reachable HTTPS URL. Trasys will immediately send a verification POST to confirm it responds with 2xx.

Select the events you want to receive. You must subscribe to at least one event.

Click Create endpoint. Your webhook secret is shown once — copy it now and store it in a secret manager. It cannot be retrieved later.

Your URL must be publicly reachable. localhost or private network addresses will fail verification. Use a tunneling tool like ngrok during local development.

URL verification

Before saving, Trasys sends a POST to your endpoint with this body:

{ "type": "endpoint.verify" }

Headers included:

X-Trasys-Event: endpoint.verify
User-Agent: Trasys-Webhook/1.0
Content-Type: application/json

Your server must respond with any 2xx status within 8 seconds. If it returns a non-2xx status or times out, the endpoint is rejected.

Minimal verification handler (Node.js)

app.post('/webhook', (req, res) => {
  // Always return 200 first, process the event after
  res.sendStatus(200);
  
  const { type } = req.body;
  if (type === 'endpoint.verify') return;
  
  // Handle real events
  handleEvent(req.body);
});

Managing endpoints

Action	Effect
Disable	Endpoint stays registered but stops receiving events
Enable	Re-activates a disabled endpoint
Edit URL/Events	Re-verifies the URL if it changes
Delete	Removes endpoint and all delivery history

REST API

You can also manage endpoints programmatically (requires user session auth, not API key):

# List endpoints
GET /webhooks/:projectId/endpoints

# Create endpoint
POST /webhooks/:projectId/endpoints
{ "url": "https://...", "events": ["alert.fired", "incident.resolved"] }

# Update endpoint
PATCH /webhooks/:projectId/endpoints/:endpointId
{ "isActive": false }

# Delete endpoint
DELETE /webhooks/:projectId/endpoints/:endpointId

# Send test event
POST /webhooks/:projectId/endpoints/:endpointId/test

Setup

Creating an endpoint

URL verification

Managing endpoints

REST API

On this page