Configuring outbound webhooks to subscribe to events

You can subscribe to the Sterling Store Engagement events and publish them to your webhook endpoints so that you are notified about the data updates in real time.

Note: The purge period for the event messages that are associated with a webhook is 90 days.

Procedure

Set up the webhook endpoint by using one of the following authorization protocols:
- OAuth
- JWT. Use either RSA256 and HMAC256
Note: Sterling Store Engagement does not connect to an HTTPS URL with a self-signed certificate. Therefore, if you are hosting HTTPS and TLS to a secure webhook, you must use a certificate that is signed by the certificate authorities and accepted by Java™ 11 JRE.
To use the POST /tenantId/v1/webhooks API, configure the webhook by using the Create Webhook API.
- If you are using OAuth as the method of authentication, use the following example:
  API name: POST /tenantId/v1/webhooks
  API request payload:
```
{
  "url": "http://host:11500/example",
  "credentials": {
    "clientId": "client id, Required for `OAUTH` authentication",
    "clientSecret": "client secret, Required for `OAUTH` authentication",
    "oauthURL": "http://host:11500/oauthToken"
  },
  "authenticationType": "OAUTH"
```
  Here,
  - url refers to the webhook URL to receive event messages.
  - clientId refers to the client ID to use for getting the OAuth token.
  - clientSecret refers to the client secret to use for getting the OAuth token.
  - oauthURL refers to the URL from which to get the OAuth token.
- If you are using JWT as the method of authentication, use the following example:
  API name: POST /tenantId/v1/webhooks
  API request payload:
```
{
  "url": "http://host:11500/example",
  "credentials": {
    "iss": "The issuer of the JWT. Required for `JWT` authentication",
    "sub": "The subject of the JWT. Required for `JWT` authentication",
    "privateKey": "The private key to sign the JWT. Required for RSA256 algorithm",
    "privateKeyId":"The private key ID",
    "algorithm": "The algorithm to use for signing the JWT. Required for `JWT` authentication, possible values are RSA256,HMAC256",
    "secret": "The secret to sign the JWT. Required for HMAC256 algorithm",
    "audience": "The recipients for whom the JWT is intended"
  },
  "authenticationType": "JWT"
}
```
  Here,
  - iss is the issuer of the JWT.
  - sub is the subject of the JWT.
  - privateKey is the private key to use to encrypt the JWT.
  - privateKeyId is the private key ID to use to encrypt the JWT.
  - algorithm is the algorithm to use to encrypt the JWT.
    RSA256 and HMAC256 are the only two encryption types that are supported.
  - secret is the secret to sign the JWT, if the algorithm used is HMAC256.
  - audience is the audience of the JWT.
Subscribe to the events that you want the webhook to receive from Sterling Store Engagement.
Use the Create Event Subscription Association API to invoke the POST /tenantId/v1/events/eventCode/subscription API.
For example, to subscribe to the inventory adjustment events, use
```
POST  tenantId/v1/events/inventoryAdjustment/subscription
```
API request payload:
```
{
    "webhooks": [
      "webhook_ID_1",
      "webhook_ID_2"
    ]
  }
```
Fetch event messages. Sometimes, you might want to fetch previously published event messages for diagnostic purposes. You can use Get Event Messages for Event Code or Get Event Messages for Webhook as shown in the following examples:
- Use GET /tenantId/v1/events/eventCode/messages to get all event messages for a specific eventCode. For example, to get all eventMessages for inventory adjustments, use the following:
```
GET  /tenantId/v1/events/inventoryAdjustment/messages
```
- Use GET /tenantId/v1/events/eventCode/ messages?startDate=XXX&endDate=YYY to get all event messages for a specific eventCode that were published between a specific time period. For example to get all eventMessages for inventory adjustments that were published between a date range:
```
GET https://tenantId/v1/events/inventoryAdjustment/messages?startDate=1630510372&endDate=1631028483
```
  The start date and end date are provided in epochMilli integer values.
- Use GET /tenantId/v1/events/eventCode/webhook/webhookId/messages?&failedToSend=false to get all event messages that were successfully published for a specific eventCode and webhookId. For example, to get all eventMessages for inventory adjustments events that were successfully published to the webhook webhook_id, use
```
GET tenantID/v1/events/inventoryAdjustment/webhook/webhook_id/messages?failedToSend=false
```