Creating a Webhook (+api)

This guide explains how to create and manage webhook subscriptions in Alvys.

Webhooks can be created either:

• From the Alvys Dashboard (UI)
• Via the Webhook Management API

What Is a Webhook Subscription?

A webhook subscription defines:

• A destination HTTPS endpoint
• A set of event types
• A signing secret (used for HMAC verification)
• An activation status

Each webhook belongs to a tenant and operates independently.

Creating a Webhook from the Dashboard

Navigate to:

Settings → Webhooks

Click Create Webhook.

You will be prompted to provide:

• Name
  A human-readable label for internal identification.

• Endpoint URL
  Must be a valid HTTPS URL (TLS 1.2+ required).

• Subscribed Events
  Select one or more event types to receive.

After saving:

• The webhook is created in Pending state.
• A secret is generated.
• Endpoint verification is triggered.

The webhook becomes Active only after successful verification.

Webhook Statuses

A webhook may have one of the following states:

• Pending — awaiting verification
• Active — verified and delivering events
• Disabled — manually disabled or auto-disabled after failures

Creating a Webhook via API

Webhook subscriptions can also be created and managed programmatically.

Create Webhook

POST /api/p/v3/webhooks

Request body example:

{
  "Name": "Production Integration",
  "SubsidiaryId": "sub-12345",
  "Url": "https://example.com/webhooks",
  "Events": [
    "tender.accepted",
    "tender.cancelled"
  ],
  "IncludePreviousAttributes": false
}

Fields:

• Name, SubsidiaryId, Url, Events — required.
• IncludePreviousAttributes — optional (default false). When true, load.changed / trip.changed events include data.diff.previousAttributes (the previous value of every changed field). See Change Diffs (data.diff).

Response:

• Webhook ID
• Signing secret
• Status
• Configuration details

List Webhooks

GET /api/p/v3/webhooks

Returns all webhooks configured for the tenant.

Retrieve Webhook Details

GET /api/p/v3/webhooks/{id}

Returns configuration, status, and metadata.

Update Webhook

PUT /api/p/v3/webhooks/{id}

Allows updating:

• Name
• Endpoint URL
• Subscribed events
• IncludePreviousAttributes (opt in/out of data.diff.previousAttributes on load.changed / trip.changed events)

Changing the endpoint URL may require re-verification.

Delete Webhook

DELETE /api/p/v3/webhooks/{id}

Removes the webhook permanently.

Enable / Disable Webhook

POST /api/p/v3/webhooks/{id}/enable
POST /api/p/v3/webhooks/{id}/disable

Disabled webhooks do not receive event deliveries.

Test Webhook

POST /api/p/v3/webhooks/{id}/test

Sends a test event to the configured endpoint.

Test deliveries:

• Follow the same signing rules
• Send a single signed POST with no retries
• Allow validation before production traffic

Rotate Webhook Secret

POST /api/p/v3/webhooks/{id}/rotate-secret

Secret rotation:

• Generates a new signing secret
• Both old and new signatures are sent during the rotation window
• Enables zero-downtime secret replacement

Limits

• Maximum 50 webhooks
• Maximum 50 event types per webhook

What Happens After Creation?

Immediately after creation:

1. A signing secret is generated.
2. Endpoint verification is required.
3. No business events are delivered until verification succeeds.

See Receiving Events for verification details.