Creating a Webhook Endpoint

You can create endpoints to receive webhook notifications either via the API or directly from the Vaulta Dashboard.

Note: All registered endpoint URLs must use https and be configured to accept HTTP POST requests with a JSON payload.

You can programmatically register a new endpoint by making a POST request to the /webhooks resource.

POST {{baseUrl}}/api/v1/webhooks

Attribute	Type	Required	Description
`data.attributes.url`	String	Yes	The `httpss` URL of your endpoint that will receive the `POST` requests.
`data.attributes.token`	String	Yes	Your secret token. This is used to generate the `x-vaulta-signature` header so you can verify the payload.
`data.attributes.deliveryMode`	String	Yes	Set to `AtLeastOnce` or `AtMostOnce`. `AtLeastOnce` (Recommended): Vaulta will retry a failed delivery (e.g., timeout or non-200 response) up to 5 times. `AtMostOnce`: Vaulta will attempt delivery once. If it fails, the event will not be retried.
`data.attributes.enabledEvents`	Array	Yes	An array of event strings you wish to subscribe to. Currently, this must include `payin.successful`.
`data.attributes.label`	String	No	A human-readable name for the webhook (e.g., "Pay-In Notification Service").
`data.attributes.supportIncluded`	Boolean	No	Defaults to `false`. If set to `true`, the full `PayIn` resource will be included in the event payload, removing the need for a follow-up API call.

This example creates a webhook endpoint that listens for the payin.successful event.

A successful 200 OK response will return the full webhook object.

You can also create and manage webhook endpoints from the Vaulta Dashboard.

On the configuration page:

Endpoint URL: Enter the httpss URL where you want to receive events.
- Label: Give your endpoint a descriptive name.
  - Secret Token: Enter the secret you will use to verify signatures.
    - Delivery Mode: Select AtLeastOnce (recommended) or AtMostOnce.
      - Events to Send: Select the payin.successful event.

Click Create Webhook to save and activate the endpoint.