Notifier Webhooks

Introduction

Webhooks allow you to receive real-time notifications as soon as an operation is executed. In this guide, we'll explore how to register, update, and manage webhooks, as well as how to retrieve events and submissions linked to those webhooks.

Following the flow described in the diagram:

1. You must register a webhook (you can have up to 3 different URLs), specifying which event subscriptions you want to receive.
2. When an event is triggered, we store the event data (linked to the relevant subscription) and attempt to send it to your registered webhook(s).
3. Each delivery attempt is logged, containing the associated event ID, the webhook URL, and the status returned by your webhook. You can also update the acknowledged field to confirm that the event was successfully received by your system.

Webhooks

Let’s start with the basics of registering, updating, fetching, and deleting webhooks.

Register a webhook

info

You can register up to 3 webhooks.

Here’s how to register one:

HTTP Post Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/

Available Subscriptions

Subscription	Description
TICKET	Receives updates related to a created ticket

Request Body Fields

Field	Type	Description
webhookUrl	string	The URL you want to receive the events.
subscriptions	array	A list of subscriptions you want to register for. At least one is required.

Sample JSON Body

{
  "webhookUrl": "https://webhook.invalid/",
  "subscriptions": ["TICKET"]
}

JSON Response

That’s it, your webhook has been registered. You should receive something like this in response:

{
  "webhookId": "00000000-0000-0000-0000-000000000000"
}

Now if you perform an operation linked to a registered event (e.g., TICKET...), you will receive this webhook.

cUrl Example

curl -X POST "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
    "webhookUrl": "https://webhook.invalid/",
    "subscriptions": [
    "TICKET"
    ]
}'

Update Webhook

Pass the webhookId you want to update, along with the new URL or subscriptions (or both).

HTTP Patch Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/

Fields

Field	Type	Required	Description
webhookId	string	Yes	The unique identifier of the webhook to update.
webhookUrl	string	No	The new URL for the webhook callback.
subscriptions	array	No	A list of subscriptions to update for the webhook.

JSON Body

{
  "webhookId": "00000000-0000-0000-0000-000000000000",
  "webhookUrl": "https://webhook.invalid.new/",
  "subscriptions": ["TICKET"]
}

In this example, we’ve updated the URL and subscriptions so that only TICKET events are delivered.

cURL Example

curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "webhookId": "c5bebcfc-41b5-4f05-a96a-428c7dc95c19",
  "webhookUrl": "https://true-usually-stingray.ngrok-free.app/webhooks/",
  "subscriptions": [
    "TICKET"
  ]
}'

Get all webhooks

List all the webhooks you’ve registered so far:

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "webhooks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "url": "https://webhook.invalid.new/",
      "subscriptions": [
        "TICKET"
      ],
      "createdAt": "2025-02-11T20:29:17.97777Z",
      "updatedAt": "2025-02-11T20:29:17.97777Z"
    }
    ...
  ]
}

Get webhook by ID

Retrieve details for a specific webhook by passing its ID as the URL path parameter.

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/WEBHOOK_ID_HERE

JSON Response

{
  "webhook": {
    "id": "00000000-0000-0000-0000-000000000000",
    "url": "https://webhook.invalid.new/",
    "subscriptions": ["TICKET"],
    "createdAt": "2025-02-11T20:29:17.97777Z",
    "updatedAt": "2025-02-11T20:29:17.97777Z"
  }
}

Delete webhook

To delete a webhook and stop receiving events on it:

HTTP Delete Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/WEBHOOK_ID_HERE

That’s it—no more events will be sent to that webhook.

Webhook Events

Events are what actually get sent to your registered webhooks. They contain the subscription type and the data associated with that event.

Event Fields

Field	Type	Description
subscription	string	Subscription is the type of event you registered in the previous step
data	object	Here you will see the data that has been sent to the webhook depending on the subscription you have entered
cursor	string	A cursor is a reference to a specific position in a paginated dataset, used to fetch the next or previous set of results efficiently.

info

The cursor is used for pagination. You call the endpoint without a cursor to get the first set of results, then use the returned cursor to fetch subsequent sets until no more results are left.

Get Events

Retrieve all the events triggered so far:

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/events/

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/events/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "events": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "subscription": "TICKET",
      "data": {
        "id": "11111111-1111-1111-1111-111111111111",
        "exampleKey": "exampleValue"
      },
      "createdAt": "2025-02-11T20:30:44.042643Z",
      "EventType": ""
    }
  ],
  "cursor": "MS0xNzM5MzA1ODQ0MDQy"
}

Get Event By Id

You can specify an event by ID, passing it as a URL path parameter:

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/events/EVENT_ID_HERE

JSON Response

{
  "event": {
    "id": "00000000-0000-0000-0000-000000000000",
    "subscription": "TICKET",
    "data": {
      "id": "11111111-1111-1111-1111-111111111111",
      "exampleKey": "exampleValue"
    },
    "createdAt": "2025-02-11T20:30:44.042643Z",
    "EventType": ""
  }
}

Webhook Submissions

Submissions track the actual delivery attempts of events to your registered webhook(s). For each attempt, you can see the status your webhook returned, the associated event ID, and whether the attempt was acknowledged as successful.

Get Submissions

Once an operation triggers a subscription, a submission is sent to your webhook. You can list them:

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/submissions/

cUrl Example

curl -X GET "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/submissions/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "eventSubmissions": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "webhookEventId": "00000000-0000-0000-0000-000000000000",
      "webhookUrl": "https://webhook.invalid.new/",
      "responseStatus": 200,
      "acknowledged": true,
      "createdAt": "2025-02-03T18:13:45.793003Z",
      "updatedAt": "0001-01-01T00:00:00Z"
    }
  ],
  "cursor": "MjMtMTczODYwNjQyNTc5Mw..."
}

Submission Fields

Now that you've understood how Webhook Submission works, let's learn how to update the submission acknowledgments received.

Field	Type	Description
webhookEventId	string	The webhookEventId is linked directly to the id returned in the previous topic.
webhookUrl	string	The url where the event was sent.
responseStatus	int	The response that your webhook returned to the Avenia
acknowledged	bool	If the answer returned by your URL is positive, the acknowledgment will be true, otherwise false
cursor	string	A cursor is a reference to a specific position in a paginated dataset, used to fetch the next or previous set of results efficiently.

Now that you've understood how Webhook Submission works, let's learn how to update the submission acknowledgments received.

Webhook Update Acknowledged

If there was an error on your end but you’ve resolved it, you can update the submission acknowledgments to confirm that you have successfully received that event’s data.

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/submissions

Request Body Field

Field	Type	Description
ids	array	A list of IDs to acknowledge. Simply add the IDs you want to mark as acknowledged.

JSON Response

{
  "ids": ["f202c6c1-4ad7-42e7-b9df-42208e146c50"]
}

With that, both Avenia API and you are aware this event submission was processed successfully.

cUrl Example

curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/notifications/webhooks/submissions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
    "ids": [
    "00000000-0000-0000-0000-000000000000"
    ]
}'

Conclusion

In this guide, you have learned how to efficiently manage Webhooks, Webhook Events, and Webhook Submissions within the system.

Now let’s see how to receive these webhooks.

We covered:

✅ Registering Webhooks – Setting up webhooks to receive real-time updates for selected events.

✅ Managing Webhooks – Updating, retrieving, and deleting webhook configurations.

✅ Webhook Events – Understanding how events are generated and linked to registered webhooks.

✅ Webhook Submissions – Tracking the delivery status of events sent to webhooks.

✅ Updating Acknowledgements – Ensuring that events are correctly received and processed.

Webhooks provide real-time event-driven notifications, eliminating the need for constant polling of APIs. By properly managing them, businesses can ensure efficient, scalable, and responsive integrations with Avenia API infrastructure. Keeping track of event submissions and acknowledgments ensures no data is lost, and debugging failed deliveries becomes simpler.

How to use CURSOR

*Extra attention for the cursor to simplify your use:** You will call the endpoint without a cursor to get the first set of results. The response will include a **cursor**, which you must pass in the next request to retrieve the following set of data. This process continues until the API stops returning a cursor, meaning there are no more results to fetch. Unlike page-based pagination, this ensures stable and consistent data retrieval, even if new entries are added while paginating. In a nutshell, imagine the cursor tokens as pages on a website, where every time you send the cursor to the endpoint, you're going through that page, and when you reach the end, there's no more cursor, simple isn't it!