Event Notification Service OAuth2 Flow
These instructions assume that you are familiar with the SFMC ENS API.
In the current Event Notification Service product (ENS, known generically as webhooks), security consists of message signing, and IP allowlisting.
Some customers prefer that the ENS authenticate with their system before pushing event notifications/webhooks. To serve these customers, SFMC supports OAuth2
password grant types.
- OAuth2 - Recommended. Client Credentials (authType=‘oauth2’, grantType=‘client_credentials’) - The customer needs to support clientId, clientSecret, authEndpoint.
- OAuth2 with Resource owner password credential (ROPC) (authType=‘oauth2’, grantType=‘password’) - The customer needs to support clientId, clientSecret, username, password, authEndpoint. This grant type is considered legacy, and is not a best practice. However, for this use-case, risk is mitigated. For many customers this scheme is sufficient.
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-urlencoded" format, per rfc6749, Appendix B. The HTTP request entity-body uses a character encoding of UTF-8 (see rfc6749, section 4.3.2).
Example for grant_type="password"
Example for grant_type=client_credentials (
password are omitted)
- Return a successful response, with
access_tokenin the response as illustrated here (see rfc6749).
- Optionally support Access_token scope.
Adding an Authentication scheme
Before ENS callbacks are configured for Authentication, clients must create an Authentication scheme.
Upon create/update calls for authType=‘oauth2’, we verify the retrieval of a token from the authEndpoint. If verification isn't successful, the request fails.
Upon 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 authId, authType, grantType, and authEndpoint.
See Create Callback.
Registers a new callback to receive event notifications. Verify your callback before you can use it in a subscription.
- 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 auth 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.
Verifies a callback so that it can receive notifications.
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.
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 : Name of the subscription. This name must be unique.
- callbackId : Unique identifier of the callback that receives the notification events. This callback must exist and must be verified.
- eventCategoryTypes : Comma-separated list of fully qualified event types for which you’re requesting notifications. Expressed as NotificationEventCategory.NotificationEventType. Review Supported Notification Events for a list of supported event categories and types
- filters : Each string in the array is a key
pair to filter on. Review Subscription Filters for a list of data items available for filtering.
Example Webhook (including relevant headers)
Update ENS callback Auth
Updates a registered callback. The callback requires up to two minutes for changes to become active.