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
password grant types.
- OAuth2 with client credentials (
grantType=‘client_credentials’) - Recommended - The customer needs to support
- OAuth2 with resource owner password credential (ROPC) (authType=‘oauth2’, grantType=‘password’) - The customer needs to support
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:
- Maintain public accessibility.
- Serve requests over TLS/HTTPS.
- Return a token within 2 seconds.
- Support many active tokens concurrently.
- Support the HTTP Basic authentication scheme for authenticating clients that were issued a client password (see rfc6749).
- Support clients making requests with parameters using the
application/x-www-form-urlencodedformat, 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
password Are Omitted
- Return a successful response, with
access_tokenin the response (see rfc6749, section 4.1.4).
Successful Response With
access_token In the Response
- Optionally support access_token scope.
Adding an Authentication scheme
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
- The sensitive fields are not returned in the response, only
Register a new callback to receive event notifications. Verify your callback before you can use it in a subscription.
See Create Callback.
- The customer captures the value of
signatureKeyin 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
verificationKeyfor the verification process.
- The parameter
authIdis 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.
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.
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 ENS Callback Authentication
Update a registered callback. The callback requires up to two minutes for changes to become active.