Managing Webhooks

Learn how to set up and manage webhooks in your Pivot organization to receive real-time notifications when events occur.

Introduction to Webhooks

Webhooks allow your organization to receive real-time notifications when specific events occur in Pivot. Instead of polling the API for changes, webhooks push data to your server automatically, enabling efficient integrations and automations.

Key Features

• Real-time notifications: Get instant updates when events occur
• Event filtering: Subscribe only to the events you care about
• Secure delivery: All webhooks are signed with HMAC-SHA256 for verification
• Delivery logging: View delivery history and troubleshoot issues
• Automatic retries: Failed deliveries are automatically retried with exponential backoff

Who Can Manage Webhooks

Accessing Webhook Management

From the sidebar menu, click your profile picture, then select Organization admin and choose your organization.

In the Organization Admin panel, click on the Integrations tab.

Within the Integrations section, you’ll find the Webhooks panel where you can view, create, and manage your organization’s webhooks.

Creating a Webhook

Click the Add Webhook button to open the webhook creation form.

Fill in the following information:

• Name: A descriptive name for your webhook (e.g., “Slack Notifications”)
• Description: Optional notes about what this webhook is used for
• Endpoint URL: The HTTPS URL where webhook payloads will be sent

Select what entity you want to receive notifications about:

• Subject Type: Choose between “Room” or “Space”
• Subject ID: Enter the UUID of the room or space

Choose which events should trigger the webhook:

• Message Sent: Triggered when a new message is sent in the subscribed room
• Room Recording Transcript Published: Triggered when a recording transcript becomes available

After clicking Create, you’ll be shown the webhook secret. This secret is used to verify webhook signatures.

Editing a Webhook

In the webhooks list, locate the webhook you want to edit.

Click the Edit icon (pencil) in the webhook row.

You can update:

• Name and Description
• Endpoint URL
• Status: Toggle between Active and Inactive
• Event Types: Add or remove event subscriptions

Click Save to apply your changes.

Viewing Webhook Logs

In the webhooks list, click the Page icon to view delivery logs for a specific webhook.

The logs show:

• Event Type: What event triggered the delivery
• Timestamp: When the delivery was attempted
• Status: Whether the delivery succeeded or failed
• Response Code: The HTTP status code from your server
• Error Message: Details if the delivery failed

Webhook Security

Verifying Webhook Signatures

Every webhook request includes a signature header that you should verify to ensure the request came from Pivot:

1. Extract the X-Pivot-Signature header from the request
2. Compute the HMAC-SHA256 of the raw request body using your webhook secret
3. Compare your computed signature with the header value

const crypto = require('crypto');

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

return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}

Security Best Practices

• Always verify signatures before processing webhook payloads
• Store secrets securely using environment variables or a secrets manager
• Use HTTPS for all webhook endpoints
• Respond quickly - return a 2xx status code within 15 seconds
• Process asynchronously - queue webhook processing for complex operations

Retry Behavior

When webhook delivery fails, Pivot automatically retries with exponential backoff:

After all retries are exhausted, organization admins will receive an email notification about the failed webhook.

Troubleshooting

Common Issues

Deleting a Webhook

In the webhooks list, locate the webhook you want to delete.

Click the Trash icon in the webhook row.

Confirm the deletion when prompted. This action cannot be undone.