Webhooks

⚠️ COMING SOON - NOT YET IMPLEMENTED

This feature is currently under development and is not available for use.

The webhook system documented on this page has not yet been implemented. Attempting to configure webhooks or use the endpoints described below will result in 404 errors.

Expected Release: Q1 2026

If you need real-time notifications about vault events, please contact support to discuss alternative solutions or be notified when webhooks become available.

Base URL: https://api.torvussecurity.com/v1 (when available)

Webhooks will allow you to receive real-time HTTP notifications when events occur in your vaults.

---

Webhook Events

Subscribe to the following events:

Event	Description
vault.created	New vault created
vault.updated	Vault settings updated
vault.released	Vault released to recipients
vault.deleted	Vault permanently deleted
document.uploaded	New document added to vault
document.deleted	Document removed from vault
recipient.added	Recipient added to vault
recipient.removed	Recipient removed from vault
checkin.completed	Check-in completed
checkin.missed	Check-in deadline missed
policy.updated	Release policy changed

---

Webhook Payload Format

All webhook POST requests use this format:

{
  "id": "evt_abc123xyz",
  "type": "vault.released",
  "created_at": "2025-10-08T17:30:00Z",
  "data": {
    "vault_id": "vault_abc123",
    "vault_name": "Digital Legacy Vault",
    "released_at": "2025-10-08T17:30:00Z",
    "recipient_count": 3
  },
  "metadata": {
    "user_id": "user_def456",
    "account_id": "acct_ghi789"
  }
}

---

Create Webhook

POST /webhooks

Register a new webhook endpoint.

Request Body

{
  "url": "https://yourserver.com/webhooks/torvus",
  "events": ["vault.released", "checkin.missed"],
  "secret": "your_webhook_secret_key",
  "enabled": true
}

Parameters:

Field	Type	Required	Description
url	string	Yes	HTTPS URL to receive webhook POSTs
events	array	Yes	List of events to subscribe to
secret	string	No	Secret for HMAC signature verification
enabled	boolean	No	Enable webhook (default: true)

Example Request

curl -X POST https://api.torvussecurity.com/v1/webhooks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhooks/torvus",
    "events": ["vault.released", "checkin.missed"],
    "secret": "your_webhook_secret"
  }'

Success Response (201 Created)

{
  "id": "webhook_xyz789",
  "url": "https://yourserver.com/webhooks/torvus",
  "events": ["vault.released", "checkin.missed"],
  "enabled": true,
  "created_at": "2025-10-08T17:35:00Z",
  "secret_set": true
}

---

List Webhooks

GET /webhooks

Get all registered webhooks.

Example Request

curl -X GET https://api.torvussecurity.com/v1/webhooks \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "data": [
    {
      "id": "webhook_xyz789",
      "url": "https://yourserver.com/webhooks/torvus",
      "events": ["vault.released", "checkin.missed"],
      "enabled": true,
      "created_at": "2025-10-08T17:35:00Z",
      "last_delivery": "2025-10-08T18:00:00Z",
      "delivery_success_rate": 100
    }
  ],
  "total": 1
}

---

Update Webhook

PATCH /webhooks/{webhook_id}

Update webhook configuration.

Request Body

{
  "events": ["vault.released", "vault.deleted", "checkin.missed"],
  "enabled": true
}

Example Request

curl -X PATCH https://api.torvussecurity.com/v1/webhooks/webhook_xyz789 \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["vault.released", "vault.deleted"],
    "enabled": true
  }'

Success Response (200 OK)

{
  "id": "webhook_xyz789",
  "url": "https://yourserver.com/webhooks/torvus",
  "events": ["vault.released", "vault.deleted"],
  "enabled": true,
  "updated_at": "2025-10-08T17:40:00Z"
}

---

Delete Webhook

DELETE /webhooks/{webhook_id}

Remove a webhook.

Example Request

curl -X DELETE https://api.torvussecurity.com/v1/webhooks/webhook_xyz789 \
  -H "Authorization: Bearer your_api_key"

Success Response (204 No Content)

No response body.

---

Verify Webhook Signatures

All webhook POST requests include an X-Torvus-Signature header with HMAC-SHA256 signature:

X-Torvus-Signature: sha256=abc123def456...

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return `sha256=${expectedSignature}` === signature;
}

// Express.js example
app.post('/webhooks/torvus', (req, res) => {
  const signature = req.headers['x-torvus-signature'];
  const isValid = verifyWebhookSignature(req.body, signature, 'your_webhook_secret');

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});

---

Retry Policy

If webhook delivery fails, Torvus will retry:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	6 hours

After 6 failed attempts, the webhook event is marked as failed. You can view failed deliveries in the dashboard.

---

Webhook Delivery Logs

GET /webhooks/{webhook_id}/deliveries

Get delivery history for a webhook.

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of records (default: 50, max: 200)
status	string	No	Filter by: success, failed, pending

Example Request

curl -X GET "https://api.torvussecurity.com/v1/webhooks/webhook_xyz789/deliveries?limit=10" \
  -H "Authorization: Bearer your_api_key"

Success Response (200 OK)

{
  "webhook_id": "webhook_xyz789",
  "deliveries": [
    {
      "id": "delivery_abc123",
      "event_type": "vault.released",
      "attempted_at": "2025-10-08T18:00:00Z",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 145,
      "attempts": 1
    },
    {
      "id": "delivery_def456",
      "event_type": "checkin.missed",
      "attempted_at": "2025-10-07T12:00:00Z",
      "status": "failed",
      "response_code": 500,
      "attempts": 6,
      "last_error": "Connection timeout"
    }
  ],
  "pagination": {
    "limit": 10,
    "total": 24
  }
}

---

Rate Limits

Endpoint	Rate Limit
POST /webhooks	20/minute
GET /webhooks	100/minute
PATCH /webhooks/{id}	50/minute
DELETE /webhooks/{id}	20/minute

Webhook Delivery Limits:

• Maximum 100 webhook deliveries per minute per endpoint
• If exceeded, deliveries are queued and delayed

---

Best Practices

1. Acknowledge Quickly: Respond with 200 OK within 5 seconds
2. Process Async: Queue webhook payload for background processing
3. Verify Signatures: Always verify HMAC signatures
4. Use HTTPS: Webhook URLs must use HTTPS
5. Monitor Failures: Check delivery logs regularly
6. Idempotent Handling: Use event IDs to prevent duplicate processing

---

Last Updated: October 8, 2025