Create Subscription

post

https://api.authvia.com/v3/accounts/{account-id}/subscriptions

scope subscriptions:create + {resource}:read

{resource}:read for the type of Subscription being created, such as business_processes:read

Create webhook subscriptions to receive real-time notifications when specific events occur in your Account. This enables your systems to stay synchronized with Customer activities, Transaction updates, and Business Process changes.

Webhooks are essential for building responsive applications that react to events as they happen, rather than polling for changes.

Info

We make an API call to the destination URL with a test payload to verify that it's valid and working, expecting a response with a status code between 200 and 399.

Warning

Your webhook endpoint must return a 2xx status code within 30 seconds to confirm receipt. Failed deliveries will be retried according to the redrive policy.

After creating a Subscription, you can manage it using the Update Subscription endpoint or monitor delivery status through the Subscription Events endpoint.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account-id

string

required

The unique identifier (AVID) of the Account.

Body Params

type

string

enum

required

length ≥ 1

The subscription type specifies the particular event the webhook will listen for and sends updates to the designated destination.

destination

string

required

length ≥ 10

The URL to which the webhook sends updates whenever the specified type of event is triggered.

description

string

length ≤ 256

Outlines subscription's purpose and intent, detailing the specific business needs it aims to fulfill.

timeout

number

5 to 15

Specifies the number of seconds before the request times out when attempting to call the configured destination URL.🔑 scope subscriptions:timeout is needed to add this attribute.

autoDisable

boolean

Used to turn off our feature of [auto disabling] webhooks. This feature is only available when attempts are set to 3 or less to avoid overloading our services with retries on a dead endpoint.

attempts

number

0 to 50

Defaults to 50

Maximum number of retry attempts for sending updates to the specified destination before it gets disabled. See the redrive page for more details.

disableCallbackURL

string

length ≥ 10

This URL will be invoked just after a webhook is disabled. A the subscription 'id' and a timestamp 'timestamp' in milliseconds are added as query parameters to this URL. See the redrive page for more details.

secret

string

length between 32 and 64

The secret key used for authentication this is to validate the request as coming from AuthVia. We recommend you use a uuid v4 for your secret for each webhook.If not provided in the request, one is generated for you at the account level. See the subscriptions verification page for more details.

disabled

boolean

Indicates whether the subscription is currently disabled true or enabled false.

conditions

object

The conditions that must be met in order for the destination of this webhook to be invoked. See the conditions page for more details.

headers

object

Static headers included with each request sent to the configured destination URL.

Responses

201Successfully created webhook subscription. Returns the subscription details including ID, destination URL, and configuration settings.

400Bad Request - The request cannot be processed due to a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401The request is valid, but server authentication failed to verify the identity. The user's access token has either expired or is not valid. Creating a new token might resolve the issue.