Event Notification

Event notification is an efficient way to inform a user of data changes that may be relevant to their organization. This enables the entire resource to be requested for appropriate updates to a user’s systems.

Paycor Marketplace makes event notifications available within the context of the user’s Products. The user subscribes to an event notifications and they are delivered via the Webhook mechanism.

The following is a step-by-step guide on how to subscribe to these available events.

Getting Access

Event notifications can be subscribed to via Postman, a http client tool.

To enable event notifications on any Product, the user will need to be granted access to Paycor’s Developer Portal. That user can have access to event notifications for the products with which they are registered.

The user must:

Register for access to Developer Portal
Register to the appropriate Product
Subscribe to event notifications for any product to which they are registered

Event Access

All requests to subscribe to event notification endpoints will require the user’s OAuth credentials and product subscription keys obtained from Paycor at the time of registration to the Developer Portal.

Events available for subscription per product set are available by performing a GET operation against the following endpoint:

https://api.paycor.com/eventsubscriptions/support/v1/events

Example Response:

[
   {
      'Entity':'Employee',
      'Event':'Add',
      'Description':'Employee updated in the Paycor system.'
   },
   {
      'Entity':'Employee',
      'Event':'Update',
      'Description':'Employee updated in the Paycor system.'
   }
]

How to Subscribe to Events

Each event is itemized by Entity (underlying resource name), Event (event name) and Description.

To subscribe to an event the user must:

Register for Event(s) Notification by making a POST request to below endpoint:
```
https://api.paycor.com/eventsubscriptions/user/registrations
```

Request Payload:

{
   WebHookUri: 'string',
   Secret: 'string', 
   Description: 'string', 
   IsPaused: boolean, 
   Filters: ['string', 'string'] 
}

Payload Input Description

WebhookUri:
- Designated receiving endpoint Url. Notifications are sent to the server at this address.
Secret:
- A string value representing the secret key intended to sign the message. This value must also be stored on the user’s server. This is how the notification is validated as coming from Paycor. If the user is unsure what to use, a GUID can be generated to use as the secret key
```
https://www.guidgenerator.com/online-guid- generator.aspx
```
Description:
- Any description to label the notification.
Filters:
- List of Event names to register for. The list is comma delimited.
IsPaused:
- This value is defaulted to “true”. It indicates whether to keep sending notifications or to pause them.

How to Make Changes to Existing Notification

Follow the steps below to modify existing Notifications:

Retrieve list of events currently registered

https://api.paycor.com/eventsubscriptions/user/registrations

Note the ID of the event(s) to be updated and used in the URI. Optionally, this request can be used to pause events notifications by setting IsPaused to “true”.

https://api.paycor.com/eventsubscriptions/user/registrations/{id}

Request body:

{
   'Id': 'string', 
   'WebHookUri': 'string', 
   'Secret': 'string', 
   'Description': 'string', 
    'IsPaused': boolean, 
   'Filters': ['string', 'string']
}

Unsubscribing from an Existing Notification

Authorized users may choose to unsubscribe from event notifications at any time by following the steps below:

Retrieve the ID of the event needing to be unsubscribed

Make a Delete request at the following URI

https://api.paycor.com/eventsubscriptions/user/registrations/{id}

This will permanently delete the subscription on Paycor systems and prevent subsequent notifications from being sent.

HMAC – Signed Message Validation

When an event notification message is sent to the user’s receiving server, the user will need to validate that it was sent from Paycor. This is to prevent acting on spoofed messages. The user may add special logging on their server to see if the URI endpoint is getting spoofed often, which may be an indication to change it.

Sample HMAC validation code

Below is sample code that could be used by a user to decrypt the signed message.

public bool Validate(string signedMessage, string eventData, string secretKey) {
   var ascii = new ASCIIEncoding();
   var secretBytes = ascii.GetBytes(secretKey);
   var cryptographer = new System.Security.Cryptography.HMACSHA256(secretBytes);
   var messageBytes = ascii.GetBytes(eventData);
   var hashedMessage = cryptographer.ComputeHash(messageBytes);
   var digest = BitConverter.ToString(hashedMessage).Replace("-", "");
   return digest == signedMessage.ToUpper();
}

Properties included within the signed message:

signedMessage: sent on the request header
eventData: request body payload
secretKey: secret key used in registering for event at Paycor.