Manage webhook subscriptions

Use the Webhook Management API to manage webhook subscriptions and inspect delivery attempts.

Create a webhook subscription

Create a new webhook subscription and include:

• The endpoint URL
• The authentication method
• The Events array, listing the event types you want to receive

Vitesse delivers only the specified event types to your endpoint. Filtering is applied at the platform level.

Send:
POST /webhooks

{
  "Url": "https://example.com/webhooks",
  "Events": [
    "PaymentRequestInitiated",
    "PaymentRequestSucceeded"
  ],
  "Auth": {
    "AuthenticationType": "Hmac"
  }
}

The response returns the created webhook subscription, including its unique identifier. Webhook subscriptions are enabled by default.

For full request and response schema details, see Create webhook.

Update a webhook subscription

Update the endpoint URL, subscribed events, or custom headers.

Send:
PUT /webhooks/{Id}

{
  "Events": [
    "PaymentRequestSucceeded",
    "PaymentRequestCancelled"
  ]
}

Only the fields included in the request are updated.

For full request and response schema details, see Update webhook.

List all webhook subscriptions

Retrieve existing webhook subscriptions for your account.

Send: GET /webhooks

The response returns a list of webhook subscriptions, including their identifiers, configured endpoint URLs, subscribed event types, and status.

View a specific webhook subscription

Send: GET /webhooks/{Id}

The response returns the details of the specified webhook subscription.

For full request and response schema details, see Retrieve all webhooks and Retrieve specified webhook.

Update webhook subscription authentication

Update the authentication method or credentials separately.

Send:
PUT /webhooks/{Id}/auth

curl -X PUT https://api.vitessepsp.com/webhooks/{webhookId}/auth \
  -H "Authorization: Bearer eyJhbGciOiJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "AuthenticationType": "Basic",
    "Username": "webhook-client",
    "Password": "w!h_7f8e9a..."
  }'

For full request and response schema details, see Update webhook authentication.

Rotate a webhook subscription secret

Generate a new secret for HMAC signature verification.

Send: PUT /webhooks/{Id}/rotateSecret

After rotating the secret:

• Vitesse signs webhook deliveries using the new secret
• Your endpoint must use the new secret to verify incoming requests
• During rotation, both v1 and v2 signatures may appear in the Vitesse-Signature header

For full request and response schema details, see Rotate secret.

Reveal a webhook subscription secret

Retrieve the current secret for a webhook subscription.

❗

Use this endpoint only when necessary. Treat the returned secret as sensitive information and store it securely.

Send: GET /webhooks/{Id}/revealSecret

For full request and response schema details, see Reveal secret.

Enable a webhook subscription

Activate event delivery.

Send:
PUT /webhooks/{Id}/enable

Disable a webhook subscription

Deactivate event delivery without deleting the subscription.

Send: PUT /webhooks/{Id}/disable

For full request and response schema details, see Enable webhook or Disable webhook.

Delete a webhook subscription

Permanently remove a webhook subscription.

Send:
DELETE /webhooks/{Id}

After deletion, Vitesse stops sending events to the endpoint.

For full request and response schema details, see Delete webhook.

Retrieve delivery attempts

Retrieve delivery metadata for a webhook subscription, including:

• Event type
• Delivery status
• Number of attempts
• HTTP response code
• Error message (if applicable)
• Timestamps

Send:
GET /webhooks/{Id}/events

📘

This endpoint returns delivery metadata only. It does not return the original webhook payload. Persist webhook payloads if you need to replay or audit event data.

For full request and response schema details, see Retrieve all webhook events.