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.
- OAuth2 with client credentials (
authType=‘oauth2’
,grantType=‘client_credentials’
) - Recommended - The customer needs to supportclientId
,clientSecret
,authUrl
. - 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:
- 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).
Example
- 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
- Return a successful response, with
access_token
in the response (see rfc6749, section 4.1.4).
Successful Response With access_token
In the Response
- 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
, andauthEndpoint
.
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 callbackverificationKey
. The callback URL (for examplehttps://example.com/sfmc-events
) returns a 200 response and captures theverificationKey
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 asNotificationEventCategory.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