Event Notification Service OAuth2 Flow

These instructions assume that you are familiar with the Salesforce Marketing Cloud Event Notification Service API (SFMC ENS API).

Since its launch, the Event Notification Service (ENS, known generically as webhooks), has used message signing and IP allowlisting security patterns.

Some customers prefer that the ENS authenticate with their system before pushing event notifications. To serve these customers, SFMC supports OAuth2 client_credentials and password grant types.

  1. OAuth2 with client credentials (authType=‘oauth2’, grantType=‘client_credentials’) - Recommended - The customer needs to support clientId, clientSecret, authUrl.
  2. OAuth2 with resource owner password credential (ROPC) (authType=‘oauth2’, grantType=‘password’) - The customer needs to support clientId, clientSecret, username, password, authUrl. This grant type is considered legacy, and is not a best practice. However, for this use-case, risk is mitigated. Many customers request this scheme.

The authorization server is expected to:

  1. Maintain public accessibility.
  2. Serve requests over TLS/HTTPS.
  3. Return a token within 2 seconds.
  4. Support many active tokens concurrently.
  5. Support the HTTP Basic authentication scheme for authenticating clients that were issued a client password (see rfc6749).

Example

  1. Support clients making requests with parameters using the application/x-www-form-urlencoded format, per rfc6749, Appendix B. The HTTP request entity-body uses the UTF-8 character encoding, according to rfc6749, section 4.3.2.

Example for grant_type="password"

Example for grant_type=client_credentials, Where username and password Are Omitted

  1. Return a successful response, with access_token in the response (see rfc6749, section 4.1.4).

Successful Response With access_token In the Response

  1. Optionally support access_token scope.

Before ENS callbacks are configured for authentication, clients must create an authentication scheme.

When creating or updating calls for authType=‘oauth2’, we verify the retrieval of a token from the authUrl. If verification isn't successful, the request fails.

When there is a delete request, we confirm that all callback associations with this authentication scheme have been removed. If verification isn't successful, the request fails.

Example Request for OAuth2 grant_type=password

Example Response for OAuth2 grant_type=password

Example Request for OAuth2 grant_type=client_credentials

Example Response for OAuth2 grant_type=client_credentials

Notes

  • The sensitive fields are not returned in the response, only authId, authType, grantType, and authEndpoint.

Register a new callback to receive event notifications. Verify your callback before you can use it in a subscription.

See Create Callback.

Example Request

Example Response

Notes

  • The customer captures the value of signatureKey in the response, to verify events via message signature.
  • The customer captures the value of verificationKey. Between the request and the response, SFMC probes, using a POST request, with an authentication token (if applicable) and the callback verificationKey. The callback URL (for example https://example.com/sfmc-events) returns a 200 response and captures the verificationKey for the verification process.
  • The parameter authId is optional. If omitted, the default message signature security measure is used. If specified, it must reference a valid authentication resource.

Verify a callback so that it can receive notifications.

See Verify Callback.

Example Request

Example Response

Create a single subscription. A subscription indicates the event types for which to receive notifications, and which callback, or webhook, to receive them on. A new subscription takes up to two minutes to become active. A subscription requires a verified callback, and allows up to 200 subscriptions per callback.

See Create Subscription.

The subscription you create is in active status, and event notifications are sent to the associated callback. Ensure that the callback you specify is ready to receive events before creating a subscription for it.

Example Request

Example Response

Notes

  • subscriptionName: The name of the subscription. This name must be unique.
  • callbackId: The unique identifier of the callback that receives the notification events. This callback must exist and must be verified.
  • eventCategoryTypes: The comma-separated list of fully qualified event types for which you’re requesting notifications. This list is expressed as NotificationEventCategory.NotificationEventType. Review Supported Notification Events for a list of supported event categories and types.
  • filters: An array of strings. Each string in the array is a key:value pair to filter on. Review Subscription Filters for a list of data items available for filtering.

Example Webhook Including Relevant Headers

Update a registered callback. The callback requires up to two minutes for changes to become active.

Example Request

Example Response