Endpoints

Endpoints are webhook URLs registered by (or for) your customers. Each endpoint belongs to a specific tenant, subscribes to one or more event types, and receives signed HTTP POST deliveries.

Key Concepts

Concept	Description
Tenant ID	Your customer's identifier — an opaque string you assign (max 255 chars)
URL	The HTTPS endpoint where events are delivered
Events	List of event types this endpoint subscribes to
Secret	HMAC-SHA256 signing secret for payload verification
Status	active, paused, or disabled

Creating Endpoints

Via Dashboard

1. Navigate to your WaaS application and open the Endpoints tab
2. Click Add Endpoint
3. Fill in:
   • Tenant ID — Your customer's identifier
   • URL — Must be HTTPS in production
   • Events — Select event types to subscribe to
4. Click Create
5. Copy the signing secret — it is only shown once

Via API

curl -X POST https://api.zyphr.dev/v1/waas/applications/{app_id}/endpoints \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_abc",
    "url": "https://customer.example.com/webhooks",
    "events": ["order.created", "order.updated"]
  }'

Response:

{
  "id": "ep_abc123",
  "tenant_id": "tenant_abc",
  "url": "https://customer.example.com/webhooks",
  "events": ["order.created", "order.updated"],
  "secret": "whsec_xxxxxxxxxxxxxxxx",
  "status": "active",
  "created_at": "2026-03-05T12:00:00Z"
}

warning

The secret is only returned on creation. Store it securely and share it with your customer through a secure channel.

Tenant Isolation

Every endpoint is scoped to a tenant_id. When you publish an event for a specific tenant, only endpoints belonging to that tenant receive the delivery. Tenants cannot see or access other tenants' endpoints or deliveries.

Publish: order.created for tenant_abc
  → Delivers to: tenant_abc's subscribed endpoints only
  → Skips: tenant_xyz's endpoints (even if subscribed to order.created)

Managing Endpoints

Updating

Update the URL, subscribed events, or status:

curl -X PATCH https://api.zyphr.dev/v1/waas/applications/{app_id}/endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://customer.example.com/webhooks/v2",
    "events": ["order.created", "order.updated", "order.cancelled"],
    "status": "active"
  }'

Pausing and Disabling

Status	Behavior
active	Receives deliveries normally
paused	Delivery is queued but not sent until resumed
disabled	No deliveries — endpoint is inactive

The circuit breaker may automatically disable an endpoint after consecutive failures. Re-enable it from the dashboard or API once the issue is resolved.

Deleting

curl -X DELETE https://api.zyphr.dev/v1/waas/applications/{app_id}/endpoints/{endpoint_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting an endpoint stops all future deliveries and removes pending retries.

Secret Rotation

Rotate an endpoint's signing secret without downtime:

curl -X POST https://api.zyphr.dev/v1/waas/applications/{app_id}/endpoints/{endpoint_id}/rotate-secret \
  -H "Authorization: Bearer YOUR_API_KEY"

During rotation, Zyphr sends deliveries signed with both the old and new secrets. Your customer updates their verification code to use the new secret, and the old secret expires after 24 hours.

Signature Verification

Every delivery includes Standard Webhooks headers:

webhook-id: msg_abc123
webhook-timestamp: 1709654400
webhook-signature: v1,base64signature...

Your customers verify payloads using HMAC-SHA256:

const crypto = require('crypto');

function verifySignature(payload, headers, secret) {
  const msgId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];

  // Check timestamp is within 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old');
  }

  const toSign = `${msgId}.${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(toSign)
    .digest('base64');

  return signature === `v1,${expected}`;
}

Embeddable Portal

Instead of building endpoint management UI yourself, embed Zyphr's portal in your application. Your customers can:

• Register and manage their own endpoints
• Select event types to subscribe to
• View delivery logs and retry failures

See Embedded Portal for setup instructions.

Plan Limits

Plan	Endpoints
Free	10
Starter	100
Pro	1,000
Scale	10,000
Enterprise	Unlimited

Next Steps

• Event Types — Define what events your platform publishes
• Delivery & Monitoring — Track delivery status and retry failures
• Embedded Portal — Let customers manage their own endpoints