Notification Systems
by sanjeevgiri

Notification Systems

Notification Systems
Notification Systems
Webhook Management V1
  • Applications with scope <action>:<applicationMetadata.id>:<resourceTypes> must be able to access all subscription endpoints with path /api/webhooks/v2/applications/{applicationId}/tenants/{tenantId}/subscriptions.
Create Subscription for Vertex App
POST /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions
Get Subscription for Vertex App
GET /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}
List Subscriptions for Vertex App
GET /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions
Update Subscription for Vertex App
PUT /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}
Delete Subscription for Vertex App
DELETE /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}
Test Subscription for Vertex App
POST /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}/tests
Create Subscription for Vertex App
Webhook Management for Vertex
POST /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions

Authentication

OAuth2

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Request body

WebhookSubscription

Responses

201 Created
Body
WebhookSubscriptionResponse
Example 1
POST https://eventwebhooks.vertexcloud.com/api/v1/api/webhooks/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions HTTP/1.1 

Content-Type: application/json

{
    "name": "ms365ForJaneDoe",
    "eventTypeCode": "einv.document.updated",
    "eventTypeVersion": 1,
    "status": "ENABLED",
    "public": true,
    "eventTags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "STRING",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "webhookRecipient": {
        "url": "https://jane.com/inbox",
        "method": "POST",
        "securityScheme": "OAUTH2",
        "hmacSha256Secret": "",
        "basicAuthUsername": "",
        "basicAuthPassword": "",
        "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
        "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
        "oauth2Audience": "jane://einvoice-inbox",
        "oauth2Scopes": "einvoice-notifications",
        "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
        "oauth2AdditionalHeaders": {
            "[...]": ""
        },
        "oauth2AdditionalProperties": {
            "[...]": "resource-123"
        },
        "additionalHeaders": {
            "[...]": "janeCoLegalEntity1"
        },
        "additionalProperties": {
            "[...]": ""
        }
    }
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z",
    "name": "ms365ForJaneDoe",
    "eventTypeCode": "einv.document.updated",
    "eventTypeVersion": 1,
    "status": "ENABLED",
    "public": true,
    "eventTags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "STRING",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "webhookRecipient": {
        "url": "https://jane.com/inbox",
        "method": "POST",
        "securityScheme": "OAUTH2",
        "hmacSha256Secret": "",
        "basicAuthUsername": "",
        "basicAuthPassword": "",
        "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
        "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
        "oauth2Audience": "jane://einvoice-inbox",
        "oauth2Scopes": "einvoice-notifications",
        "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
        "oauth2AdditionalHeaders": {
            "[...]": ""
        },
        "oauth2AdditionalProperties": {
            "[...]": "resource-123"
        },
        "additionalHeaders": {
            "[...]": "janeCoLegalEntity1"
        },
        "additionalProperties": {
            "[...]": ""
        }
    },
    "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "subscriptionType": "WEBHOOK"
}
show more
Get Subscription for Vertex App
Webhook Management for Vertex
GET /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}

Authentication

OAuth2

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
id
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Responses

200 OK
Body
WebhookSubscriptionResponse
Example 1
GET https://eventwebhooks.vertexcloud.com/api/v1/api/webhooks/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions/c86fcc87-a137-4c37-8d19-17edc7199fef HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z",
    "name": "ms365ForJaneDoe",
    "eventTypeCode": "einv.document.updated",
    "eventTypeVersion": 1,
    "status": "ENABLED",
    "public": true,
    "eventTags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "BOOLEAN",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "webhookRecipient": {
        "url": "https://jane.com/inbox",
        "method": "POST",
        "securityScheme": "OAUTH2",
        "hmacSha256Secret": "",
        "basicAuthUsername": "",
        "basicAuthPassword": "",
        "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
        "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
        "oauth2Audience": "jane://einvoice-inbox",
        "oauth2Scopes": "einvoice-notifications",
        "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
        "oauth2AdditionalHeaders": {
            "[...]": ""
        },
        "oauth2AdditionalProperties": {
            "[...]": "resource-123"
        },
        "additionalHeaders": {
            "[...]": "janeCoLegalEntity1"
        },
        "additionalProperties": {
            "[...]": ""
        }
    },
    "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "subscriptionType": "WEBHOOK"
}
show more
List Subscriptions for Vertex App
Webhook Management for Vertex
GET /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions

Authentication

OAuth2

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Request parameters

page
integer optional
Default:
0
Example:
0
size
integer optional
Min: 1
Max: 100
Default:
20
Example:
20
sort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. The sort order defaults to DESC when left unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

pageSort=field1,ASC&pageSort=field2,DESC

Default:
updatedAt,DESC
Example:
updatedAt,DESC
applicationId
string optional

Vertex managed application identifier

Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
tenantId
string optional

Vertex customer organizations segment environment id.

Example:
90483dc3-10da-4fc9-9d71-3ec1b37b8a90
tags
string optional

The tags for filtering are provided as a URL-encoded array of tag objects, each containing a key and a value.

For instance, if your tag value is [{“key”:“docNum”, “value”: “3a”}], you’ll need to URL-encode it to %5B%7B%22key%22%3A%22docNum%22%2C%20%22value%22%3A%20%223a%22%7D%5D.

During the filtering process, all tags are combined using an AND operation, meaning a match only occurs if all specified tags are present.

Example:
%5B%7B%22key%22%3A%22docNum%22%2C%20%22value%22%3A%20%223a%22%7D%5D
eventTypeCode
string optional

Event type name

Example:
einvoice.transmitted
eventTypeVersion
integer optional

Event type version

Example:
0
subscriptionCreatedAtFrom
string date-time optional

The lower bound (start) of the event’s creation timestamp in UTC. This will default to today - 7 days.

Example:
2025-06-08T20:13:02.123Z
subscriptionCreatedAtTo
string date-time optional

The upper bound (end inclusive) of the event’s creation timestamp in UTC.

Example:
2025-01-08T20:13:02.123Z

Responses

200 OK
Body
Object
content
Array of WebhookSubscriptionResponse
Example 1
GET https://eventwebhooks.vertexcloud.com/api/v1/api/webhooks/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "content": [
        {
            "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
            "version": 1,
            "createdBy": "john.doe@vertexinc.com",
            "createdAt": "2025-06-05T16:26:41.567Z",
            "updatedBy": "jane.doe@vertexinc.com",
            "updatedAt": "2025-06-05T17:26:41.567Z",
            "name": "ms365ForJaneDoe",
            "eventTypeCode": "einv.document.updated",
            "eventTypeVersion": 1,
            "status": "ENABLED",
            "public": true,
            "eventTags": [
                {
                    "key": "owner",
                    "value": "john.doe@vertexinc.com",
                    "valueType": "NUMBER",
                    "defaultValue": "john.doe@vertexinc.com"
                }
            ],
            "webhookRecipient": {
                "url": "https://jane.com/inbox",
                "method": "POST",
                "securityScheme": "OAUTH2",
                "hmacSha256Secret": "",
                "basicAuthUsername": "",
                "basicAuthPassword": "",
                "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
                "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
                "oauth2Audience": "jane://einvoice-inbox",
                "oauth2Scopes": "einvoice-notifications",
                "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
                "oauth2AdditionalHeaders": {
                    "[...]": ""
                },
                "oauth2AdditionalProperties": {
                    "[...]": "resource-123"
                },
                "additionalHeaders": {
                    "[...]": "janeCoLegalEntity1"
                },
                "additionalProperties": {
                    "[...]": ""
                }
            },
            "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
            "subscriptionType": "WEBHOOK"
        }
    ]
}
show more
Update Subscription for Vertex App
Webhook Management for Vertex
PUT /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}

Authentication

OAuth2

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
id
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Request body

WebhookSubscription

Responses

200 OK
Body
WebhookSubscriptionResponse
Example 1
PUT https://eventwebhooks.vertexcloud.com/api/v1/api/webhooks/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions/c86fcc87-a137-4c37-8d19-17edc7199fef HTTP/1.1 

Content-Type: application/json

{
    "name": "ms365ForJaneDoe",
    "eventTypeCode": "einv.document.updated",
    "eventTypeVersion": 1,
    "status": "ENABLED",
    "public": true,
    "eventTags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "BOOLEAN",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "webhookRecipient": {
        "url": "https://jane.com/inbox",
        "method": "POST",
        "securityScheme": "OAUTH2",
        "hmacSha256Secret": "",
        "basicAuthUsername": "",
        "basicAuthPassword": "",
        "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
        "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
        "oauth2Audience": "jane://einvoice-inbox",
        "oauth2Scopes": "einvoice-notifications",
        "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
        "oauth2AdditionalHeaders": {
            "[...]": ""
        },
        "oauth2AdditionalProperties": {
            "[...]": "resource-123"
        },
        "additionalHeaders": {
            "[...]": "janeCoLegalEntity1"
        },
        "additionalProperties": {
            "[...]": ""
        }
    }
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z",
    "name": "ms365ForJaneDoe",
    "eventTypeCode": "einv.document.updated",
    "eventTypeVersion": 1,
    "status": "ENABLED",
    "public": true,
    "eventTags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "NUMBER",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "webhookRecipient": {
        "url": "https://jane.com/inbox",
        "method": "POST",
        "securityScheme": "OAUTH2",
        "hmacSha256Secret": "",
        "basicAuthUsername": "",
        "basicAuthPassword": "",
        "oauth2ClientId": "d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e",
        "oauth2ClientSecret": "_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL",
        "oauth2Audience": "jane://einvoice-inbox",
        "oauth2Scopes": "einvoice-notifications",
        "oauth2TokenUrl": "https://auth0.jane.com/oauth/token",
        "oauth2AdditionalHeaders": {
            "[...]": ""
        },
        "oauth2AdditionalProperties": {
            "[...]": "resource-123"
        },
        "additionalHeaders": {
            "[...]": "janeCoLegalEntity1"
        },
        "additionalProperties": {
            "[...]": ""
        }
    },
    "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "subscriptionType": "WEBHOOK"
}
show more
Delete Subscription for Vertex App
Webhook Management for Vertex
DELETE /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}

Authentication

OAuth2

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
id
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Responses

204 No Content
Example 1
DELETE https://eventwebhooks.vertexcloud.com/api/v1/api/v2/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions/c86fcc87-a137-4c37-8d19-17edc7199fef HTTP/1.1 

HTTP/1.1 204 No Content
Test Subscription for Vertex App
Webhook Management for Vertex
POST /api/webhooks/v1/applications/{applicationId}/tenants/{tenantId}/subscriptions/{id}/tests

Authentication

OAuth2

Use this operation to verify your subscription endpoint’s setup. We’ll do this by:

  • Creating a test event (EventType.testPayload) tailored to your subscription.
  • Sending this test event to your subscription.endpoint.url, distinguished by the vertex-webhooks-test=true HTTP header, Subect prefixed [TEST] in emails
  • It’s critical that the application receiving this test notification is designed to log the request, bypass any business logic for the test event, and return a 200 OK response within 500ms.

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
id
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Responses

200 OK
Body
TestEventDeliveryResponse
Example 1
POST https://eventwebhooks.vertexcloud.com/api/v1/api/webhooks/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/subscriptions/c86fcc87-a137-4c37-8d19-17edc7199fef/tests HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "status": "SUCCEEDED",
    "event": {
        "tags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com",
                "valueType": "STRING",
                "defaultValue": "john.doe@vertexinc.com"
            }
        ],
        "expiryIntervalDays": "3",
        "payload": "{\"documentId\": \"123\"}",
        "expiresAt": "2025-06-06T15:09:44.789Z",
        "eventType": {
            "id": "einvDocumentUpated",
            "code": "einv.document.updated",
            "name": "E-Invoice Document Updated Event",
            "description": "This state indicates the outbound e-invoice reached a terminal state",
            "version": 1,
            "schemaVersion": "0.0.1",
            "schemaRef": "https://xyz.github.io/einv/api/einv-events-openapi.yaml",
            "tags": [
                {
                    "key": "owner",
                    "value": "john.doe@vertexinc.com",
                    "valueType": "STRING",
                    "defaultValue": "john.doe@vertexinc.com"
                }
            ]
        },
        "activeSubscriptions": [
            "c86fcc87-a137-4c37-8d19-17edc7199fef"
        ],
        "payloadRefId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "payloadSizeKb": 199,
        "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "version": 1,
        "createdBy": "john.doe@vertexinc.com",
        "createdAt": "2025-06-05T16:26:41.567Z",
        "updatedBy": "jane.doe@vertexinc.com",
        "updatedAt": "2025-06-05T17:26:41.567Z"
    },
    "subscriptionId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "deliveryCompletionIntervalMs": 199,
    "deliveryCompletionMessage": "ok"
}
show more
Event Management V1
  • Applications with scope all:<applicationMetadata.id>:all must be able to access event management endpoints with path /api/notifications/v2/applications/{applicationId}/tenants/{tenantId}/…
Create Event for Vertex App
POST /api/notifications/v1/applications/{applicationId}/tenants/{tenantId}/eventtypes/{eventTypeId}/events
Get Large Event Payload Presigned Download URL for Vertex App
POST /api/notifications/v1/applications/{applicationId}/events/{id}
Create Event for Vertex App
Notification Management for Vertex Applications
POST /api/notifications/v1/applications/{applicationId}/tenants/{tenantId}/eventtypes/{eventTypeId}/events

Authentication

OAuth2

Only application with matching scope for applicationId path variable can access this endpoint. For example application with scope all:EINV:all can create events using endpoint /api/v2/application/EINV/…

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
tenantId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
eventTypeId
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Request body

Event

Responses

201 Created
Body
EventResponse
Example 1
POST https://eventwebhooks.vertexcloud.com/api/v1/api/notifications/v1/applications/EINV/tenants/c86fcc87-a137-4c37-8d19-17edc7199fef/eventtypes/c86fcc87-a137-4c37-8d19-17edc7199fef/events HTTP/1.1 

Content-Type: application/json

{
    "tags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "NUMBER",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "expiryIntervalDays": "3",
    "payload": "{\"documentId\": \"123\"}"
}

HTTP/1.1 201 Created 

Content-Type: application/json

{
    "tags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "NUMBER",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "expiryIntervalDays": "3",
    "payload": "{\"documentId\": \"123\"}",
    "expiresAt": "2025-06-06T15:09:44.789Z",
    "eventType": {
        "id": "einvDocumentUpated",
        "code": "einv.document.updated",
        "name": "E-Invoice Document Updated Event",
        "description": "This state indicates the outbound e-invoice reached a terminal state",
        "version": 1,
        "schemaVersion": "0.0.1",
        "schemaRef": "https://xyz.github.io/einv/api/einv-events-openapi.yaml",
        "tags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com",
                "valueType": "NUMBER",
                "defaultValue": "john.doe@vertexinc.com"
            }
        ]
    },
    "activeSubscriptions": [
        "c86fcc87-a137-4c37-8d19-17edc7199fef"
    ],
    "payloadRefId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "payloadSizeKb": 199,
    "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z"
}
show more
Get Large Event Payload Presigned Download URL for Vertex App
Notification Management for Vertex Applications
POST /api/notifications/v1/applications/{applicationId}/events/{id}

Authentication

OAuth2

Applications with scope all:EINV:WebhookSubscriptions or all:EINV:all can access this /api/v2/application/EINV/events/uuid to get a download url.

Applications or user with scope profile and matching profile.tenant.id == event.tenantId can access this link as well.

Path variables

applicationId
string required
Min length: 3
Max length: 255
Example:
EINV
id
string uuid required
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef

Responses

200 OK
Body
string uri
Example:
https://download-url.vertexcloud.com/xyz
Example 1
POST https://eventwebhooks.vertexcloud.com/api/v1/api/v2/applications/EINV/events/c86fcc87-a137-4c37-8d19-17edc7199fef HTTP/1.1 

HTTP/1.1 200 OK 

Content-Type: application/json

https://download-url.vertexcloud.com/xyz
Models
EventDeliveryStat
All of
EventStat
BaseEventDeliveryStat
BaseEventDeliveryStat
Object
totalEventDeliveries
integer
Example:
6
totalEventDeliveryErrors
integer
Example:
0
totalEventDeliveryRetries
integer
Example:
0
totalEventDeliveryReplays
integer
Example:
0
minDeliveryCompletionMs
integer
Example:
199
maxDeliveryCompletionMs
integer
Example:
199
p95DeliveryCompletionMs
integer

This represents the delivery completion interval in milliseconds, where 95% of events within a user-specified time window are smaller than or equal to this value.

Example:
199
BaseEventDeliveryResponse
Object
status
EventDeliveryStatus read-only
Example:
SUCCEEDED
event
EventResponse read-only
subscriptionId
string read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
deliveryCompletionIntervalMs
integer read-only
Example:
199
deliveryCompletionMessage
string read-only
Example:
ok
EventDeliveryResponse

We store each delivery attempt as a separate record. Our system makes a total of five automated delivery attempts. If all five attempts fail, the final record’s status will be PERMANENTLY_FAILED, while the previous four will show a FAILED status.

Here’s how the automated attempts progress:

  • Attempt 1: PENDING → FAILED (at time t1)
  • Attempt 2: RETRYING → FAILED (at t1 + 120 seconds)
  • Attempt 3: RETRYING → FAILED (at t1 + 240 seconds)
  • Attempt 4: RETRYING → FAILED (at t1 + 480 seconds)
  • Attempt 5: RETRYING → FAILED (at t1 + 960 seconds)
  • Additionally, you can initiate a manual delivery attempt via a “replay” operation, which would look like this:

Manual Replay: RETRYING → SUCCEEDED

All of
Example: 
{
    "replayAttempt": 1,
    "retryAttempt": 1,
    "status": "SUCCEEDED",
    "event": {
        "tags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com",
                "valueType": "NUMBER",
                "defaultValue": "john.doe@vertexinc.com"
            }
        ],
        "expiryIntervalDays": "3",
        "payload": "{\"documentId\": \"123\"}",
        "expiresAt": "2025-06-06T15:09:44.789Z",
        "eventType": {
            "id": "einvDocumentUpated",
            "code": "einv.document.updated",
            "name": "E-Invoice Document Updated Event",
            "description": "This state indicates the outbound e-invoice reached a terminal state",
            "version": 1,
            "schemaVersion": "0.0.1",
            "schemaRef": "https://xyz.github.io/einv/api/einv-events-openapi.yaml",
            "tags": [
                {
                    "key": "owner",
                    "value": "john.doe@vertexinc.com",
                    "valueType": "BOOLEAN",
                    "defaultValue": "john.doe@vertexinc.com"
                }
            ]
        },
        "activeSubscriptions": [
            "c86fcc87-a137-4c37-8d19-17edc7199fef"
        ],
        "payloadRefId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "payloadSizeKb": 199,
        "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "version": 1,
        "createdBy": "john.doe@vertexinc.com",
        "createdAt": "2025-06-05T16:26:41.567Z",
        "updatedBy": "jane.doe@vertexinc.com",
        "updatedAt": "2025-06-05T17:26:41.567Z"
    },
    "subscriptionId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "deliveryCompletionIntervalMs": 199,
    "deliveryCompletionMessage": "ok",
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z"
}
Object
replayAttempt
integer read-only
Default:
0
Example:
0
retryAttempt
integer read-only
Default:
0
Example:
0
BaseEventDeliveryResponse
BaseObject
TestEventDeliveryResponse
All of
BaseEventDeliveryResponse
EventDelivery

The fundamental structure for all outgoing notification events.

Object
Example: 
{
    "event": {
        "tags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com"
            }
        ],
        "expiryIntervalDays": "3",
        "payload": "{\"documentId\": \"123\"}",
        "payloadRefId": "c517f9b8-d0e5-42a9-b3a7-5e9c0c1b7e4f",
        "payloadSizeKb": "55"
    },
    "eventExpiresAt": "2025-06-06T15:09:44.789Z",
    "eventId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "replayAttempt": 1,
    "retryAttempt": 1,
    "subscription": {
        "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
        "name": "ms365ForJaneDoe",
        "additionalProperties": {
            "[...]": "janeCoBusinessUnit1"
        },
        "eventTags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com"
            }
        ]
    }
}
event
Event
eventExpiresAt
string date-time read-only
Example:
2025-06-06T15:09:44.789Z
eventId
string uuid read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
replayAttempt
integer read-only
Default:
0
Example:
0
retryAttempt
integer read-only
Default:
0
Example:
0
subscription
Object
id
string read-only

Vertex cloud subscription id

Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
name
string read-only

Subscription name

Example:
ms365ForJaneDoe
additionalProperties
Object read-only

Additional properties defined in Subscription.endpoint.additionalProperties

additional properties
string
Min length: 3
Max length: 255
Example:
janeCoBusinessUnit1
eventTags
Array of Tag read-only

Configurations for subscription delivery criteria

show more
EventStat
Object
totalEventTypes
integer
Example:
3
totalOrgAccounts
integer
Example:
2
totalSubscriptions
integer
Example:
6
totalEvents
integer
Example:
6
totalApproximateIngestionErrors
integer

We track errors that occur when processing and storing events from applications. For both synchronous and asynchronous event ingestion, we monitor incoming requests. However, this count may sometimes be an approximation due to internal errors.

Example:
0
minPayloadSize
integer
Example:
199
maxPayloadSize
integer
Example:
199
p95PayloadSize
integer

This represents the payload size observed, where 95% of events within a user-specified time window are smaller than or equal to this value.

Example:
199
EventDeliveryStatus
string
Enumeration:
PENDING

This state can transition to either SUCCEEDED or FAILED state

SUCCEEDED

This is a terminal state

FAILED

This state is a terminal state for a specific delivery attempt. Next delivery attemtp with start with RETRYING state. If delivery attempt as maxed out (5 attempts), then this state will delivery instance will transition to PERMANENTLY_FAILED.

RETRYING
PERMANENTLY_FAILED
Example:
SUCCEEDED
WebhookRecipientMethod
string
Enumeration:
POST
PUT
PATCH
Example:
POST
BaseObject

When as resource is first created, the udpatedAt and updatedBy will be the same as createdAt and createdBy respectively.

Object
id
string uuid read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
version
integer read-only
Example:
1
createdBy
string read-only
Example:
john.doe@vertexinc.com
createdAt
string date-time read-only
Example:
2025-06-05T16:26:41.567Z
updatedBy
string read-only
Example:
jane.doe@vertexinc.com
updatedAt
string date-time read-only
Example:
2025-06-05T17:26:41.567Z
TagValueType
string
Enumeration:
STRING
BOOLEAN
NUMBER
Tag
Object
key
string required
Min length: 3
Max length: 255
Example:
owner
value
string required
Min length: 3
Max length: 255
Example:
john.doe@vertexinc.com
valueType
TagValueType
Default:
STRING
Example:
STRING
defaultValue
string
Example:
john.doe@vertexinc.com
ApplicationMetadata

Client applications that interact with the notification-service

Object
id
string

Notification system defined immutable identifier for application. This must be globally unique within the notification-system.

Min length: 3
Max length: 255
Example:
EINV
code
string

Client system defined identifier for application. This must be globally unique within the notification-system.

name
string required
Min length: 3
Max length: 255
Example:
Vertex E-Invoicing
description
string required
Min length: 3
Max length: 255
Example:
Vertex E-Invoicing Service
tags
Array of Tag
Max items: 20
EventType
Object
id
string

This value must be globally unique within notification-service and is immutable.

Min length: 3
Max length: 255
Example:
einvDocumentUpated
code
string

This value combined with version must be globally unique within notification-service and is defined by client application system. Following naming convention is recommended: <appcode>.<resource>.<resourceState>

Min length: 3
Max length: 255
Example:
einv.document.updated
name
string

This is human readable name for an event type. This can be used in user interfaces.

Min length: 3
Max length: 255
Example:
E-Invoice Document Updated Event
description
string
Min length: 3
Max length: 255
Example:
This state indicates the outbound e-invoice reached a terminal state
version
integer
Default:
0
Example:
0
schemaVersion
string required
Min length: 3
Max length: 11
Example:
0.0.1
schemaRef
string uri required
Example:
https://xyz.github.io/einv/api/einv-events-openapi.yaml
tags
Array of Tag

Applicaton defined tags that can be used for subscription and event filtering criteria

Max items: 20
ApplicationEventType

Event types are logical identifiers for distinct actions or states within client applications. Examples include: einvoice.received, einvoice.transmitted, taxCalculation.completed, exemptionCertificate.processed, and taxReporting.completed. These are owned by application developers responsible for building application that prouce and consume events.

All of
EventType
Object
defaultRetentionIntervalDays
integer
Min: 3
Max: 180
Default:
3
Example:
3
public
boolean

The Cloud Portal Tools MFE for webhooks SHALL use this attribute to filter out events that aren’t publicly subscribable. Setting it to false indicates internal usage.

Default:
true
testPayload
string

This will be used for testing subscription endpoints during configuration.

Example:
{documentId: 123}
applicationCode
string required
Min length: 3
Max length: 255
Example:
EINV
applicationName
string required
Min length: 3
Max length: 255
Example:
Vertex E-Invoicing
platformFeatureCodes
string required

This readonly property serves as a key for discovering event types by linking them to specific products. On the Webhooks MFE screen, this information is leveraged to show customers only the event types relevant to their product feature code entitlements. For example:

  • 1199 represents Connectors
  • 1200 represents einvoicing events
  • 100 represents OSeries events
  • 1200,1199 represents einvoicing Connectors
  • 100,1199 represents OSeries Connectors

This value is evaluated from the client applications scope that is prefixed with platformFeatureCodes::<value>

Min length: 3
Max length: 255
Example:
1200
SubscriptionType
string
Enumeration:
WEBHOOK
EMAIL
Example:
WEBHOOK
EventTemplate
Object
code
string required

Client application defined globally unique value across notification-service

Min length: 3
Max length: 255
Example:
einv.document.updated.email
eventType
string required
Min length: 3
Max length: 255
Example:
einv.document.updated
subscriptionType
SubscriptionType required
Example:
EMAIL
title
string required

Used in Subject for Emails, sent as vertex-notification-title header for webhooks

Min length: 3
Max length: 255
Example:
E-Invoice Document Updated
sender
string required

Application name and event type

Example:
Vertex E-Invoicing
senderAddress
string

Application name and event type for webhooks or sender email address for email subscription type

Example:
jane.doe@vertexinc.com
payloadTemplate
string

Used to generate email body content or webhook event payload content

Example:
Hi {{EventData->Customer_FirstName}}, Thank you for reaching out to us. We appreciate your business. - Vertex inc.
ApplicationEventTypesInternalCatalog
Object
Example: 
{
    "applicationEventTypes": [
        {
            "applicationMetadata": {
                "id": "EINV",
                "code": "EINV",
                "name": "Vertex E-Invoicing",
                "description": "Vertex E-Invoicing Service",
                "tags": [
                    {
                        "key": "owner",
                        "value": "john.doe@vertexinc.com",
                        "valueType": "BOOLEAN",
                        "defaultValue": "john.doe@vertexinc.com"
                    }
                ]
            },
            "eventTypes": [
                {
                    "id": "einvDocumentUpdated"
                    "name": "einv.document.updated",
                    "description": "This state indicates the outbound e-invoice reached a terminal state",
                    "version": 1,
                    "schemaVersion": "0.0.1",
                    "schemaRef": "https://xyz.github.io/einv/api/einv-events-openapi.yaml",
                    "tags": [
                        {
                            "key": "owner",
                            "value": "john.doe@vertexinc.com",
                            "valueType": "BOOLEAN",
                            "defaultValue": "john.doe@vertexinc.com"
                        }
                    ],
                    "defaultRetentionIntervalDays": 3,
                    "public": true,
                    "testPayload": "{customerName: John.Doe, documentId: 123}",
                    "platformFeatureCodes": "1200",
                    "emailSubscriptionTemplate": {
                        "code": "einv.document.updated.email",
                        "eventType": "einv.document.updated",
                        "subscriptionType": "EMAIL",
                        "title": "E-Invoice Document Updated",
                        "sender": "Vertex E-Invoicing",
                        "senderAddress": "jane.doe@vertexinc.com",
                        "payloadTemplate": "Hi {{EventData->customerName}}, Thank you for reaching out to us. We appreciate your business.      - Vertex inc."
                    }
                }
            ]
        }
    ]
}
applicationEventTypes
Array
Object
applicationMetadata
ApplicationMetadata
eventTypes
Array
All of
EventType
Object
defaultRetentionIntervalDays
integer
Example:
3
public
boolean
Default:
true
testPayload
string
Example:
{documentId: 123}
platformFeatureCodes
string
Example:
1200
emailSubscriptionTemplate
EventTemplate
webhookSubscriptionTemplate
EventTemplate
WebhookRecipient
Object
url
string uri required
Min length: 13
Max length: 255
Example:
https://jane.com/inbox
method
WebhookRecipientMethod
securityScheme
WebhookRecipientSecurityScheme
hmacSha256Secret
string nullable

Conditionally required for is HMAC_SHA256 security scheme

Min length: 3
Max length: 255
basicAuthUsername
string nullable

Conditionally required for is Basic Auth security scheme

Min length: 3
Max length: 255
basicAuthPassword
string nullable

Conditionally required for is Basic Auth security scheme

Min length: 3
Max length: 255
oauth2ClientId
string nullable

Conditionally required for is OAuth2 security scheme

Min length: 3
Max length: 255
Example:
d3049b4c-8e7c-4a1f-a5f1-3b9d0b6c2a1e
oauth2ClientSecret
string nullable

Conditionally required for is OAuth2 security scheme

Min length: 3
Max length: 255
Example:
_nS7yQzPp5RjF2hT8cVx9eYw0uIaLkBmCgDdEfGhIjKkL
oauth2Audience
string nullable

Conditionally required for is OAuth2 security scheme

Min length: 3
Max length: 255
Example:
jane://einvoice-inbox
oauth2Scopes
string nullable

Conditionally required for is OAuth2 security scheme

Min length: 3
Max length: 255
Example:
einvoice-notifications
oauth2TokenUrl
string uri nullable

Conditionally required for is OAuth2 security scheme

Min length: 13
Max length: 255
Example:
https://auth0.jane.com/oauth/token
oauth2AdditionalHeaders
Object

During token creation, some systems require header attributes for token creation.

additional properties
string
oauth2AdditionalProperties
Object

Optional properties used for OAuth2 token generation. For example microsoft idP requires sending of resource key.

additional properties
string
Min length: 3
Max length: 255
Example:
resource-123
additionalHeaders
Object

You can include additional, arbitrary HTTP headers with your event deliveries. These headers are incredibly flexible and can be used to convey extra context that aids in event processing on the receiving end.

Here are some common ways these custom headers are utilized:

  • Identifying Environments: A custom header could indicate whether an event is for production or test processing, allowing the receiving system to route or handle it accordingly.
  • Providing Partner Details: Headers can carry specific information about the partner system, such as their legal entity, business unit, or other relevant organizational details.

These properties can also be accessed on the notification endpoint using the subscription.additionalHeaders attibute

additional properties
string
Min length: 3
Max length: 255
Example:
janeCoLegalEntity1
additionalProperties
Object

You can define custom properties during subscripton creation to be included with event deliveries. These properties will appear within the eventDelivery.subscription.additionalProperties field for each delivered event. These properties will be merged as key value pairs in the event payload object.

additional properties
string
Min length: 3
Max length: 255
show more
WebhookRecipientSecurityScheme
string
Enumeration:
OAUTH2
BASIC_AUTH
HMAC_SHA256

HMAC signature included in header vertex-hmac-sha256 using a shared secret key

NONE
Example:
OAUTH2
EmailRecipient
Object
name
string required
Min length: 3
Max length: 255
Example:
Jane Doe
emailAddress
string email

Email address is preferred. If not available, userId is used for lookup with UserService.

Min length: 3
Max length: 255
Example:
jane.doe@vertexinc.com
userId
string uuid

Conditionally required vertex user service generated user identifier (immutable). In existing form, this is the same as actorId

Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
SubscriptionStatus
string
Enumeration:
DISABLED
ENABLED
SUSPENDED
Example:
ENABLED
Subscription
Object
name
string required
Min length: 3
Max length: 255
Example:
ms365ForJaneDoe
eventTypeCode
string required
Min length: 3
Max length: 255
Example:
einv.document.updated
eventTypeVersion
integer
Default:
0
Example:
0
type
SubscriptionType required
status
SubscriptionStatus required
public
boolean

The Cloud Portal Tools MFE for webhooks SHALL use this attribute to filter out event type subscriptions that aren’t directly managed by our customers. Setting it to false indicates internally managed subscriptions.

Default:
true
Example:
true
eventTags
Array of Tag

Events are delivered when all specified tags match.

webhookRecipient
WebhookRecipient

Conditionally required for WEBHOOK subscription type

emailRecipient
EmailRecipient

Conitionally required for EMAIL subscription type

SubscriptionResponse
All of
BaseObject
Subscription
Object
tenantId
string uuid read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
Event
Object
tags
Array of Tag

The event producer creates tags for each event. It primarily uses the tag keys and their default values as specified in the event type object. However, the producer can also add additional keys not originally defined there. These tags are crucial because subscriptions are matched against them to determine whether an event should be delivered.

expiryIntervalDays
string nullable

Default value from event type is used when not provided in the request.

Min length: 3
Max length: 90
Example:
3
payload
string required

The event payload is represented as a string. If the content is binary, client systems must Base64 encode it before sending the event.

Min length: 3
Example:
{"documentId": "123"}
EventResponse
All of
Example: 
{
    "tags": [
        {
            "key": "owner",
            "value": "john.doe@vertexinc.com",
            "valueType": "BOOLEAN",
            "defaultValue": "john.doe@vertexinc.com"
        }
    ],
    "expiryIntervalDays": "3",
    "payload": "{\"documentId\": \"123\"}",
    "expiresAt": "2025-06-06T15:09:44.789Z",
    "eventType": {
        "id": "einvDocumentUpated",
        "code": "einv.document.updated",
        "name": "E-Invoice Document Updated Event",
        "description": "This state indicates the outbound e-invoice reached a terminal state",
        "version": 1,
        "schemaVersion": "0.0.1",
        "schemaRef": "https://xyz.github.io/einv/api/einv-events-openapi.yaml",
        "tags": [
            {
                "key": "owner",
                "value": "john.doe@vertexinc.com",
                "valueType": "BOOLEAN",
                "defaultValue": "john.doe@vertexinc.com"
            }
        ]
    },
    "activeSubscriptions": [
        "c86fcc87-a137-4c37-8d19-17edc7199fef"
    ],
    "payloadRefId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "payloadSizeKb": 199,
    "tenantId": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "id": "c86fcc87-a137-4c37-8d19-17edc7199fef",
    "version": 1,
    "createdBy": "john.doe@vertexinc.com",
    "createdAt": "2025-06-05T16:26:41.567Z",
    "updatedBy": "jane.doe@vertexinc.com",
    "updatedAt": "2025-06-05T17:26:41.567Z"
}
Event
Object
expiresAt
string date-time read-only
Example:
2025-06-06T15:09:44.789Z
eventType
EventType read-only
activeSubscriptions
Array read-only
string
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
payloadRefId
string uuid read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
payloadSizeKb
integer read-only
Example:
199
tenantId
string uuid
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
BaseObject
WebhookSubscription
Object
name
string required
Min length: 3
Max length: 255
Example:
ms365ForJaneDoe
eventTypeCode
string required
Min length: 3
Max length: 255
Example:
einv.document.updated
eventTypeVersion
integer
Default:
0
Example:
0
status
SubscriptionStatus required
public
boolean

The Cloud Portal Tools MFE for webhooks SHALL use this attribute to filter out event type subscriptions that aren’t directly managed by our customers. Setting it to false indicates internally managed subscriptions.

Default:
true
Example:
true
eventTags
Array of Tag

Events are delivered when all specified tags match.

webhookRecipient
WebhookRecipient

Conditionally required for WEBHOOK subscription type

WebhookSubscriptionResponse
All of
BaseObject
WebhookSubscription
Object
tenantId
string uuid read-only
Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
subscriptionType
SubscriptionType
Pagination Parameters
page
integer optional
Default:
0
Example:
0
size
integer optional
Min: 1
Max: 100
Default:
20
Example:
20
sort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. The sort order defaults to DESC when left unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

pageSort=field1,ASC&pageSort=field2,DESC

Default:
updatedAt,DESC
Example:
updatedAt,DESC
Subscription Params
applicationId
string optional

Vertex managed application identifier

Example:
c86fcc87-a137-4c37-8d19-17edc7199fef
tenantId
string optional

Vertex customer organizations segment environment id.

Example:
90483dc3-10da-4fc9-9d71-3ec1b37b8a90
tags
string optional

The tags for filtering are provided as a URL-encoded array of tag objects, each containing a key and a value.

For instance, if your tag value is [{“key”:“docNum”, “value”: “3a”}], you’ll need to URL-encode it to %5B%7B%22key%22%3A%22docNum%22%2C%20%22value%22%3A%20%223a%22%7D%5D.

During the filtering process, all tags are combined using an AND operation, meaning a match only occurs if all specified tags are present.

Example:
%5B%7B%22key%22%3A%22docNum%22%2C%20%22value%22%3A%20%223a%22%7D%5D
eventTypeCode
string optional

Event type name

Example:
einvoice.transmitted
eventTypeVersion
integer optional

Event type version

Example:
0
subscriptionCreatedAtFrom
string date-time optional

The lower bound (start) of the event’s creation timestamp in UTC. This will default to today - 7 days.

Example:
2025-06-08T20:13:02.123Z
subscriptionCreatedAtTo
string date-time optional

The upper bound (end inclusive) of the event’s creation timestamp in UTC.

Example:
2025-01-08T20:13:02.123Z
Common Headers
idempotency-key
string optional

This is application defined identifier for event instance, and it will be included in all event delivery attempts.

vertex-webhook-test
string optional

We’ll include this header both when you create a subscription (if testSubscriptionEndpoint is true) and when you perform a subscription test operation.

Common Responses
202 Accepted
409 Conflict
400 Bad Request
401 Unauthorized
Applied to all operations
403 Forbidden
Applied to all operations
404 Not Found