Configuring a Subscription to meet your needs:

There are a number of approaches that can be taken.

Unauthenticated Webhook

This is the simplest approach. Choose this if you want an unsecured Webhook. This is useful for development and testing purposes.

NB: Bear in mind, if your endpoint is exposed to the public internet, then it may be open to abuse.

{
  "name": "my-subscription",
  "url": "https://my-subscription/updates",
  "status": "active",
  "updateType": "consent-receipts",
  "authentication": {
    "authType": "none"
  }
}

This will result in requests like this:

URL: https://my-subscription/updates

BODY: { ... payload ... }

Webhook with API Key (Header)

This approach is the best combination of simple and secure.

{
  "name": "my-subscription",
  "url": "https://my-subscription/updates",
  "status": "active",
  "updateType": "consent-receipts",
  "authentication": {
    "authType": "api-key",
    "apiKeyAuth": {
      "location": "header",
      "value": "ABC1234",
      "key": "X-API-Key"
    },
  }
}

This will result in requests like this:

URL: https://my-subscription/updates

HEADERS: X-API-Key: ABC1234

BODY: { ... payload ... }

Webhook with API Key (Query Parameter)

Choose this approach if, for technical reasons, using HTTP headers is not possible.

NB: Putting an API Key in a URL will mean that it likely logged and may be seen by unknown persons.

{
  "name": "my-subscription",
  "url": "https://my-subscription/updates",
  "status": "active",
  "updateType": "consent-receipts",
  "authentication": {
    "authType": "api-key",
    "apiKeyAuth": {
      "location": "query",
      "value": "ABC1234",
      "key": "key"
    },
  }
}

This will result in requests like this:

URL: https://my-subscription/updates?key=ABC123

BODY: { ... payload ... }

Webhook with Bearer token

Choose this approach if you or your organisation require Bearer tokens.

NB: You will be required to manually replace expired tokens.

{
  "name": "my-subscription",
  "url": "https://my-subscription/updates",
  "status": "active",
  "updateType": "consent-receipts",
  "authentication": {
    "authType": "token",
    "token": "ABC1234"
  }
}

This will result in requests like this:

URL: https://my-subscription/updates

HEADERS: Authorization: Bearer ABC123

BODY: { ... payload ... }

Webhook with OAuth2 Client Credentials

Choose this approach if you or your organisation require Bearer tokens obtained from OAuth2 Client Credentials.

{
  "name": "my-subscription",
  "url": "https://my-subscription/updates",
  "status": "active",
  "updateType": "consent-receipts",
  "authentication": {
    "authType": "oauth2",
    "oauth2Auth": {
        "grantType": "client-credentials",
        "authenticationUrl": "https://localhost:8080/oauth/token",
        "contentType": "application-form-urlencoded",
        "clientId": "<client id>",
        "clientSecret": "<client secret>",
        "scope": "openid"
    }
  }
}

This will result in requests like this:

URL: https://my-subscription/updates

HEADERS: Authorization: Bearer ABC123

BODY: { ... payload ... }

Salesforce

This provides integration with the Salesforce Connector. It requires a refresh token and a refresh url. The service will manage getting the first access token as well as renewing it upon expiry.

{
  "name": "my-subscription",
  "url": "https://hello.my.salesforce.com/services/apexrest/MyLifeDigital/EffectivePermissions",
  "status": "active",
  "updateType": "effective-permission",
  "authentication": {
    "authType": "token",
    "refreshToken": "{your refresh token}"
    "refreshUrl": "https://hello.my.salesforce.com/services/oauth2/token"
  }
}

This will result in requests like this:

URL: https://my-subscription/updates

HEADERS: Authorization: Bearer {access token}

BODY: { ... payload ... }