Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypha-docs.plinqx.app/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let you receive real-time notifications when events occur in Plinqx. Configure webhooks to integrate with external systems or trigger automations.

​
Overview

Webhooks provide:
  • Real-time Notifications: Get notified immediately when events occur
  • External Integration: Connect Plinqx to external systems
  • Automation: Trigger workflows in other platforms
  • Event History: Track all webhook deliveries

​
Supported Events

Plinqx emits webhook events for:
EventDescription
approval.requestedAn approval request is created
approval.completedAn approval request is resolved
approval.expiredAn approval request expires
tool.calledA tool is executed
tool.errorA tool execution fails
invocation.startedA tool invocation begins
invocation.completedA tool invocation completes successfully
invocation.failedA tool invocation fails
connection.health_changedA connection health status changes
connection.credential_expiringA connection credential is about to expire

​
Creating Webhooks

1

Navigate to Webhooks

Click Webhooks in the sidebar (under Administration).
2

Create Webhook

Click Create Webhook.
3

Configure Webhook

Provide:
  • Name: Descriptive name for the webhook
  • URL: Endpoint URL to receive webhooks
  • Events: Select which events to subscribe to
  • Secret: Optional secret for signature verification
  • Headers: Optional custom headers to include
4

Save

Click Save to create the webhook.

​
Webhook Security

​
Signature Verification

Plinqx signs webhook payloads for verification:
  • Header: X-Plinqx-Signature
  • Timestamp: X-Plinqx-Timestamp
  • Event Type: X-Plinqx-Event
Verify signatures using your webhook secret: 
const crypto = require('crypto');

function verifySignature(payload, signature, timestamp, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp);
  hmac.update(payload);
  const expected = hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
Always verify webhook signatures to ensure requests are from Plinqx and haven’t been tampered with.

​
Webhook Payload

Webhook payloads include:
  • Event Type: The event that triggered the webhook
  • Timestamp: When the event occurred
  • Data: Event-specific data
  • Metadata: Additional context
Example payload: 
{
  "event": "invocation.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "invocationId": "inv_abc123",
    "toolName": "sf_query",
    "status": "COMPLETED",
    "result": { ... }
  },
  "metadata": {
    "tenantId": "tenant_123",
    "principalId": "principal_456"
  }
}

​
Webhook Delivery

​
Delivery Status

Webhook deliveries have statuses:
StatusDescription
PENDINGQueued for delivery
SUCCESSSuccessfully delivered
FAILEDDelivery failed
RETRYINGRetrying after failure

​
Retry Policy

Plinqx automatically retries failed deliveries:
  • Exponential Backoff: Increasing delays between retries
  • Max Retries: Configurable maximum retry attempts
  • Timeout: Configurable request timeout

​
Managing Webhooks

​
Viewing Deliveries

1

Open Webhook

Click on a webhook to view details.
2

View Deliveries

See all delivery attempts and their status.

​
Retrying Failed Deliveries

1

View Failed Deliveries

Navigate to failed deliveries.
2

Retry

Click Retry to manually retry a failed delivery.

​
Disabling Webhooks

Temporarily disable webhooks without deleting them:
  1. Open the webhook
  2. Toggle Enabled OFF
  3. Webhook stops receiving events

​
Deleting Webhooks

Deleting a webhook permanently removes it and all delivery history.
  1. Open the webhook
  2. Click Delete
  3. Confirm deletion

​
Webhook Statistics

View webhook statistics:
  • Total Deliveries: Count of all delivery attempts
  • Success Rate: Percentage of successful deliveries
  • Average Response Time: Average time to receive response
  • Failed Deliveries: Count of failed attempts

​
Best Practices

Verify Signatures

Always verify webhook signatures for security

Handle Idempotency

Use event IDs to handle duplicate deliveries

Respond Quickly

Respond to webhooks within timeout window

Monitor Failures

Set up alerts for webhook delivery failures

​
Next Steps

View Audit Logs

See webhook events in audit logs

Configure Policies

Set up policies that trigger webhook events