PEXA Notification Service [$]
PEXA Notification Service [$] from PEXA — 6 path(s) described in OpenAPI.
PEXA Notification Service [$] from PEXA — 6 path(s) described in OpenAPI.
openapi: 3.1.0
info:
title: Notification Service [$]
description: |
The Push Notifications Service handles delivering notifications via webhook to subscribers and manages the registration of subscribers for specific events. This API caters to various functions including updating, deleting, and creating registration details, as well as rotating the shared secret for secure communication. <br> <br> Pricing: <br> This API is a premium API service and usage of the API is billed. Please contact the API support team [here](mailto:apisupport@pexa.com.au) for more information. <br> <br> This API uses the OAuth 2.0 protocol for authentication and authorization. It supports the following OAuth 2.0 flow: <br> - Client Credentials <br> <br> Scopes are used to grant an application different levels of access to data. Each API endpoint will require specific scopes. <br> The scopes are listed against each API endpoint. <br> <br> For more information, see the following guides: <br> - [PEXA Webhooks Guide](../../docs/definitions/webhooks/) <br> - [Authentication](../../../Exchange/docs/documentation/)
version: 1.0.0
contact:
email: 'apisupport@pexa.com.au'
servers:
- url: 'https://api.pexa.com.au'
description: Production server
- url: 'https://api-tst.pexalabs.com.au'
description: Non-Prod server
tags:
- name: NotificationRegistration
description: Registration related endpoints
paths:
/v3/notification-registrations:
post:
tags:
- NotificationRegistration
summary: Create registration details (V3)
description: Registers a webhook endpoint to start receiving PEXA event notifications, with support for enhanced authentication modes. Use authenticationMode HMAC for standard shared secret verification, or HMAC_OAUTH to additionally authenticate webhook delivery using OAuth 2.0 Client Credentials for integrators with strict inbound security requirements. Returns a system-generated shared secret that must be stored securely and used to verify the HMAC signature on all incoming webhook requests. The shared secret expires after 30 days and must be rotated before expiry. <br>Scopes:<br><i>create:notification_registrations</i> (non-prod)<br><i>create:notification_registrations</i> (prod)
operationId: createNotificationRegistrationV3
security:
- oauth2:
- create:notification_registrations
tags:
- Create registration V3
requestBody:
description: Registration details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookNotificationRegistrationRequest'
examples:
hmacOnly:
summary: HMAC authentication
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'WORKSPACE_PARTICIPANT_ADDED'
- 'SECRET_EXPIRY'
attributes:
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC'
hmacOauthPrivateKeyJwt:
summary: HMAC + OAuth (private_key_jwt)
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'WORKSPACE_PARTICIPANT_ADDED'
- 'SECRET_EXPIRY'
attributes:
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'private_key_jwt'
audience: 'https://api.example.com'
scope: 'api.scope1 api.scope2'
hmacOauthClientSecret:
summary: HMAC + OAuth (client_secret)
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'WORKSPACE_PARTICIPANT_ADDED'
- 'SECRET_EXPIRY'
attributes:
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'client_secret'
clientSecret: 'secret-67890'
scope: 'api.scope1 api.scope2'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookNotificationRegistrationResponseV3'
examples:
createRegistrationWithHMAC:
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
sharedSecret: '38e5d78c-d642-42d1-8064-0082dc87c4e5'
sharedSecretExpiry: '2025-03-13 04:12:51.574000 +00:00'
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
createRegistrationWithHMACOAUTH:
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
sharedSecret: '38e5d78c-d642-42d1-8064-0082dc87c4e5'
sharedSecretExpiry: '2025-03-13 04:12:51.574000 +00:00'
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'private_key_jwt'
audience: 'https://api.example.com'
scope: 'api.scope1 api.scope2'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
createRegistrationWithHMACOAUTHClientSecret:
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
sharedSecret: '38e5d78c-d642-42d1-8064-0082dc87c4e5'
sharedSecretExpiry: '2025-03-13 04:12:51.574000 +00:00'
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'client_secret'
scope: 'api.scope1 api.scope2'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
examples:
subscriberIdMissing:
summary: SubscriberId couldn't be fetched from token
value:
errors:
- code: 'GA.NOTIF.400009'
message: "SubscriberId couldn't be fetched from token"
field: null
webhookURIInvalid:
value:
errors:
- code: 'GA.NOTIF.400012'
message: 'Webhook URI is invalid'
field: 'webhookURI'
domainNotWhitelisted:
value:
errors:
- code: 'GA.NOTIF.400014'
message: 'The webhook domain has not been whitelisted'
field: 'webhookURI'
authenticationModeInvalid:
value:
errors:
- code: 'GA.NOTIF.400026'
message: 'Invalid authentication mode'
field: 'authenticationMode'
authConfigMissing:
summary: authConfig required for HMAC_OAUTH
value:
errors:
- code: 'GA.NOTIF.400027'
message: 'authConfig is required when authenticationMode is HMAC_OAUTH'
field: 'authConfig'
authUrlNotWhitelisted:
summary: Auth URL domain not whitelisted
value:
errors:
- code: 'GA.NOTIF.400029'
message: 'The auth URL domain has not been whitelisted'
field: 'authUrl'
clientIdInvalid:
summary: clientId is required
value:
errors:
- code: 'GA.NOTIF.400030'
message: 'clientId is required and must not be blank'
field: 'clientId'
clientAuthMethodInvalid:
summary: Invalid clientAuthMethod
value:
errors:
- code: 'GA.NOTIF.400031'
message: 'Invalid clientAuthMethod'
field: 'clientAuthMethod'
clientSecretMissing:
summary: clientSecret required for client_secret method
value:
errors:
- code: 'GA.NOTIF.400032'
message: 'clientSecret is required when clientAuthMethod is client_secret'
field: 'clientSecret'
authConfigNotAllowed:
summary: authConfig not allowed for HMAC mode
value:
errors:
- code: 'GA.NOTIF.400034'
message: 'authConfig must not be provided when authenticationMode is HMAC'
field: 'authConfig'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.401004'
message: 'Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.403003'
message: 'Forbidden'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- message: 'Internal Server Error'
/v3/notification-registrations/{registrationId}:
put:
tags:
- NotificationRegistration
summary: Update registration details (V3)
description: Updates the webhook URI, event types, or authentication configuration for an existing registration. Supports switching between HMAC and HMAC_OAUTH modes. Use HMAC_OAUTH to add OAuth 2.0 Client Credentials authentication on top of HMAC for enhanced security. The shared secret is unchanged and not returned in this response. Use the secret rotation endpoint if you need to renew it. <br>Scopes:<br><i>edit:notification_registrations</i> (non-prod)<br><i>edit:notification_registrations</i> (prod)
operationId: updateNotificationRegistrationV3
security:
- oauth2:
- edit:notification_registrations
tags:
- Update registration V3
parameters:
- in: path
name: registrationId
schema:
type: string
format: uuid
required: true
description: UUID of the registration to update
example: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
requestBody:
description: Updated registration details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookNotificationRegistrationRequest'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookNotificationRegistrationUpdateResponseV3'
examples:
updateRegistrationWithHMAC:
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
updateRegistrationWithHMACOAUTH:
value:
notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
webhookURI: 'https://example.com/webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'private_key_jwt'
audience: 'https://api.example.com'
scope: 'api.scope1 api.scope2'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
examples:
webhookURIInvalid:
value:
errors:
- code: 'GA.NOTIF.400012'
message: 'Webhook URI is invalid'
field: 'webhookURI'
authConfigMissing:
summary: authConfig required for HMAC_OAUTH
value:
errors:
- code: 'GA.NOTIF.400027'
message: 'authConfig is required when authenticationMode is HMAC_OAUTH'
field: 'authConfig'
authUrlNotWhitelisted:
value:
errors:
- code: 'GA.NOTIF.400029'
message: 'The auth URL domain has not been whitelisted'
field: 'authUrl'
clientSecretMissing:
value:
errors:
- code: 'GA.NOTIF.400032'
message: 'clientSecret is required when clientAuthMethod is client_secret'
field: 'clientSecret'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.401004'
message: 'Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.403003'
message: 'Forbidden'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.404007'
message: 'Registration not found for given id: 091f7d22-88a9-4b64-bc51-e1ea8bb8dc42'
field: 'registrationId'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- message: 'Internal Server Error'
/v2/notification-registrations:
get:
tags:
- NotificationRegistration
summary: Get notification registrations
description: Retrieve registration details. If registrationId parameter is provided, returns specified registration details. If not provided, returns an array of all registrations ordered by updated_at timestamp in descending order <br>Scopes:<br><i>view:notification_registrations</i> (non-prod)<br><i>view:notification_registrations</i> (prod)
operationId: getNotificationRegistrationsV2
security:
- oauth2:
- view:notification_registrations
tags:
- Get registration V2
parameters:
- in: query
name: registrationId
schema:
type: string
format: uuid
required: false
description: Optional registration ID to filter results. If not provided, returns all registrations ordered by updated_at timestamp in descending order.
example: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
- in: query
name: page
schema:
type: integer
default: 1
minimum: 1
required: false
description: Determines which page of registrations to retrieve
- in: query
name: limit
schema:
type: integer
default: 10
minimum: 1
maximum: 20
required: false
description: Number of records per page
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/components/schemas/PagedNotificationRegistrations'
examples:
registrationWithHMAC:
summary: Registration with HMAC authentication
value:
page:
page: 1
totalRecords: 1
pageRecords: 1
limit: 10
records:
- notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
integratorId: '344a6eb8-1201-4b80-a279-084713e300ef'
integratorType: 'BROKER'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
sharedSecret: '38e5d78c-d642-42d1-8064-0082dc87c4e5'
sharedSecretExpiry: '2025-03-13 04:12:51.574000 +00:00'
webhookURI: 'https://push-notifications.pexa.com.au/notifications-webhook'
authenticationMode: 'HMAC'
registrationWithHMACOAUTH:
summary: Registration with HMAC + OAuth authentication
value:
page:
page: 1
totalRecords: 1
pageRecords: 1
limit: 10
records:
- notificationType: 'WEBHOOK'
eventTypes:
- 'SECRET_EXPIRY'
- 'CHECKLIST_CHECKED'
integratorId: '344a6eb8-1201-4b80-a279-084713e300ef'
integratorType: 'BROKER'
registrationId: '28e5d78c-d642-42d1-8064-0082dc87c4e5'
subscriberId: '202'
sharedSecret: '38e5d78c-d642-42d1-8064-0082dc87c4e5'
sharedSecretExpiry: '2025-03-13 04:12:51.574000 +00:00'
webhookURI: 'https://push-notifications.pexa.com.au/notifications-webhook'
authenticationMode: 'HMAC_OAUTH'
authConfig:
authUrl: 'https://auth.example.com/oauth/token'
clientId: 'client-12345'
clientAuthMethod: 'private_key_jwt'
audience: 'https://api.example.com'
scope: 'api.scope1 api.scope2'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
examples:
subscriberIdMissing:
summary: SubscriberId couldn't be fetched from token
value:
errors:
- code: 'GA.NOTIF.400009'
message: "SubscriberId couldn't be fetched from token"
field: null
invalidRegistrationId:
summary: Invalid registration ID format
value:
errors:
- code: 'GA.NOTIF.400000'
message: 'Invalid UUID string'
field: 'registrationId'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.401004'
message: 'Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.403003'
message: 'Forbidden'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- message: 'Internal Server Error'
/v1/notification-registrations:
post:
tags:
- NotificationRegistration
summary: Create registration details
description: Registers a webhook endpoint to start receiving PEXA event notifications. Returns a system-generated shared secret that must be stored securely and used to verify the HMAC signature on all incoming webhook requests. The shared secret expires after 30 days and must be rotated before expiry. <br>Scopes:<br><i>create:notification_registrations</i> (non-prod)<br><i>create:notification_registrations</i> (prod)
operationId: createNotificationRegistration
security:
- oauth2:
- create:notification_registrations
tags:
- Create registration
requestBody:
description: Registration details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNotificationRegistrationRequest'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationRegistrationCreateDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
examples:
subscriberIdMissing:
summary: Subscriber Id is missing
value:
errors:
- code: 'GA.NOTIF.400009'
message: "Subscriber Id is missing"
field: null
webhookURIInvalid:
summary: Invalid webhook URI
value:
errors:
- code: 'GA.NOTIF.400012'
message: 'Webhook URI is invalid'
field: 'webhookURI'
eventTypeListEmpty:
summary: Event type list is empty
value:
errors:
- code: 'GA.NOTIF.400013'
message: 'Must not be empty'
field: 'eventTypes'
domainNotWhitelisted:
summary: Domain not whitelisted
value:
errors:
- code: 'GA.NOTIF.400014'
message: 'The webhook domain has not been whitelisted'
field: 'webhookURI'
eventTypeListInvalid:
summary: Event type list is invalid
value:
errors:
- code: 'GA.NOTIF.400015'
message: 'Invalid eventTypes: ["Invalid_event1", "Invalid_event2"]'
field: 'eventTypes'
eventTypeListDuplicate:
summary: Event type list has duplicates
value:
errors:
- code: 'GA.NOTIF.400016'
message: 'Duplicate eventTypes: ["CHECKLIST_CHECKED", "CHECKLIST_UNCHECKED"]'
field: 'eventTypes'
invalidFormat:
summary: Invalid format provided
value:
errors:
- code: 'GA.NOTIF.400017'
message: 'Invalid format provided'
field: 'webhookURI'
invalidJson:
summary: Invalid JSON
value:
errors:
- code: 'GA.NOTIF.400018'
message: 'JSON parse error'
field: null
duplicateRegistration:
summary: Duplicate registration
value:
errors:
- code: 'GA.NOTIF.400019'
message: 'Registration already exists with this combination'
field: 'webhookURI'
mandatoryEventTypesMissing:
summary: Mandatory event types missing
value:
errors:
- code: 'GA.NOTIF.400020'
message: 'Mandatory event types are missing'
field: 'eventTypes'
additionalEventTypeMissing:
summary: An additional event type is required
value:
errors:
- code: 'GA.NOTIF.400021'
message: 'There should be at least one more event present apart from mandatory event(s)'
field: 'eventTypes'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.401004'
message: 'Unauthorized'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- code: 'GA.NOTIF.403003'
message: 'Forbidden'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
example:
errors:
- message: 'Internal Server Error'
/v1/notification-registrations/{registrationId}:
put:
tags:
- NotificationRegistration
summary: Update registration details
description: Updates the webhook URI or event types for an existing registration. The shared secret is unchanged and not returned in this response. Use the secret rotation endpoint if you need to renew it. <br>Scopes:<br><i>edit:notification_registrations</i> (non-prod)<br><i>edit:notification_registrations</i> (prod)
operationId: updateNotificationRegistration
security:
- oauth2:
- edit:notification_registrations
tags:
- Update a subscriber's notification preference
parameters:
- in: path
name: registrationId
schema:
type: string
required: true
description: UUID of the registration
requestBody:
description: Registration details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateNotificationRegistrationRequest'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationRegistrationDto'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationServiceErrorResponse'
examples:
subscriberIdMissing:
summary: Subscriber Id is missing
value:
errors:
- code: 'GA.NOTIF.400009'
message: "Subscriber Id is missing"
field: null
webhookURIInvalid:
summary: Invalid webhook URI
value:
errors:
- code: 'GA.NOTIF.400012'
message: 'Webhook URI is invalid'
field: 'webhookURI'
eventTypeListEmpty:
summary: Event type list is empty
value:
errors:
- code: 'GA.NOTIF.400013'
message: 'Must not be empty'
field: 'eventTypes'
domainNotWhitelisted:
summary: Domain not whitelisted
value:
errors:
- code: 'GA.NOTIF.400014'
message: 'The webhook domain has not been whitelisted'
field: 'webhookURI'
eventTypeListInvalid:
summary: Event type list is invalid
value:
errors:
- code: 'GA.NOTIF.400015'
message: 'Invalid eventTypes: ["Invalid_event1", "Invalid_event2"]'
field: 'eventTypes'
eventTypeListDuplicate:
summary: Event type list has duplicates
value:
errors:
- code: 'GA.NOTIF.400016'
message: 'Duplicate eventTypes: ["CHECKLIST_CHECKED", "CHECKLIST_UNCHECKED"]'
field: 'eventTypes'
invalidFormat:
summary: Invalid format provided
value:
errors:
- code: 'GA.NOTIF.400017'
message: 'Invalid format provided'
field: 'webhookURI'
invalidJson:
summary: Invalid JSON
value:
errors:
- code: 'GA.NOTIF.400018'
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pexa/refs/heads/main/openapi/pexa-notification-service-openapi.yaml