What Is Webhook Security

Webhooks require the external application or service to send the event information to the adapter using the HTTP protocol.

Before processing these messages, you must use a security logic to authenticate or validate that the messages are from a valid source or sender.

Additionally, external applications or services may transmit validation information during the exchange of messages. For example, the message may include an event-specific key, which you can compare with the key sent with the event. This allows you to verify if the message is sent from the correct source.

Webhooks can implement security at the following stages:

Registration of the webhook during activation. See Validation During Webhook Registration.
Reception of webhook messages during runtime. See Authentication and Validation of Webhook Messages.

Note:

Some scenarios may require a webhook trigger to invoke APIs of the external application, thereby requiring authentication mechanisms before invoking. To handle this scenario, you can design a composite security policy in the connection section of the adapter definition document. For more information on how to configure a trigger connection that can support inbound message authentication, see Create a Trigger Connection Definition to Invoke Protected Endpoints.

Validation During Webhook Registration

An external application or service may enforce validation during the webhook registration process.

For complete details about the webhook registration process, see Understand Event Subscription.

During this registering process, the external application may enforce the following requirements:

Respond to a ping sent to the endpoint, which the adapter receives.

The response may either be a simple acknowledgment or a more specific or custom response message.
Store security information regarding the validation of a runtime message from the external application.
Initialize the external application with the information that allows it to obtain authorization or authentication to send the message successfully to Oracle Integration.

You can use the Rapid Adapter Builder to model all of these scenarios.

The most common requirement of registration are ping requests. If the registration of the endpoint is manual, the integration that processes the event must be activated before a ping can be acknowledged. Additionally, the trigger must model a validationRequests logic that returns the acknowledgment for the ping request.

You can model this logic as shown in the following example, where a condition is applied to discern the source of the ping. In this scenario, the acknowledgment is issued if the request has a header that contains a key of x-custom-event and a value of ping. The response is created with a HTTP status code of 204. The response can be of any content that the event producer requires.

"validationRequests": [
  {
    "condition": "${.request.headers.\"x-custom-event\"==\"ping\"}",
    "response": {
      "status": 204
    }
  }
],

Additionally, in some scenarios, the registration might require processing of the ping or incoming request. In such scenarios, you can use a flow to model the additional logic. The set of objects in the validationRequests are executed to ensure that the message is valid. If the conditions are not fulfilled, the incoming message is not executed during runtime.

Authentication and Validation of Webhook Messages

You can implement authentication and validation mechanisms for webhook messages during the runtime execution.

In the connection section of the adapter definition document, you can define the runtime security enforcement for inbound messages as a composite security policy. The trigger security policy supports both inbound and outbound sections.

Additionally, some scenarios may require the webhook trigger to invoke APIs of the external application, thus requiring authentication mechanisms for invoking. These scenarios include:

Configuration of a trigger that reads data from the external application to allow for selection of options.
Dynamic schema creation that requires reading of metadata information from the external application.
Subscription registration and deregistration that requires calling the external application's API to create these entities.

The composite security policy consists of the following important properties:

policyOutbound: Models the external application's authentication scheme for invoking its API. Most applications use the standard OAuth policies to protect their APIs and permit outbound calls.
policyInbound: Models the security schemes that allow Oracle Integration to authenticate or validate runtime messages sent by external applications.

Note:

External applications and services mostly influence the design of webhook security. Most services use digital signatures to validate webhook messages.

The policyInbound section supports digital signatures. The valid values are:

DIGITAL_SIGNATURE
HMAC_SIGNATURE_VALIDATION
RSA_SIGNATURE_VALIDATION
JWT_VALIDATION

Here's a sample code that shows a security policy definition with Github triggers and the HMAC_SIGNATURE_VALIDATION managed policy:

"securityPolicies": [
   {
     "type": "composite",
     "description": "This policy is used by OIC for validating incoming requests as well as for invoking GitHub APIs",
     "displayName": "GitHub security policy",
     "scope": "TRIGGER",
     "policyOutbound": {
       "type": "managed",
       "policy": "OAUTH2.0_AUTHORIZATION_CODE_CREDENTIALS",
       "securityProperties": [
         {
           "name": "oauth.client.id",
           "displayName": "Client Id",
           "description": "Client Id",
           "shortDescription": "Client Id",
           "required": true,
           "hidden": false
         },
         {
           "name": "oauth.client.secret",
           "displayName": "Client Secret",
           "description": "Client Secret",
           "shortDescription": "Client Secret",
           "required": true,
           "hidden": false
         },
         {
           "name": "oauth.access.token.uri",
           "default": "https://github.com/login/oauth/access_token",
           "required": false,
           "hidden": true
         },
         {
           "name": "oauth.scope",
           "displayName": "Scope",
           "description": "The scope of the access request",
           "shortDescription": "scope",
           "required": false,
           "hidden": false
         },
         {
           "name": "oauth.auth.code.uri",
           "default": "https://github.com/login/oauth/authorize",
           "required": false,
           "hidden": true
         },
         {
           "name": "authRequest",
           "default": "${(.securityProperties.\"oauth.auth.code.uri\") + \"?response_type=code&client_id=\" + (.securityProperties.\"oauth.client.id\") + \"&redirect_uri=${redirect_uri}&scope=\" + (.securityProperties.\"oauth.scope\")}",
           "required": true,
           "hidden": true
         },
         {
           "name": "accessTokenRequest",
           "description": "Access Token Request that should be used to fetch the access token",
           "shortDescription": "Example: -X <Method> -H <headers> -d <string-data> <access-token-uri>?<query params>",
           "default": "${\"-X POST -H \" + \"\\\"Accept: application/json\\\" -H \\\"Content-Type: application/x-www-form-urlencoded\\\" -d \\\"false\\\" \\\"\" +  (.securityProperties.\"oauth.access.token.uri\") + \"?code=${auth_code}&client_id=\" + (.securityProperties.\"oauth.client.id\") + \"&redirect_uri=${redirect_uri}&client_secret=\" + (.securityProperties.\"oauth.client.secret\") + \"&grant_type=authorization_code\\\"\"}",
           "required": true,
           "hidden": true
         },
         {
           "name": "refreshTokenRequest",
           "description": "Refresh Token Request that should be used to fetch the access token",
           "shortDescription": "Example: -X <Method> -H <headers> -d <string-data> <refresh-token-uri>?<query params>",
           "required": true,
           "default": "${\"-X POST -H \" + \"\\\"Accept: application/json\\\" -H \\\"Content-Type: application/x-www-form-urlencoded\\\" -d \\\"false\\\" \\\"\" +  (.securityProperties.\"oauth.access.token.uri\") + \"?refresh_token=${refresh_token}&client_id=\" + (.securityProperties.\"oauth.client.id\") + \"&redirect_uri=${redirect_uri}&client_secret=\" + (.securityProperties.\"oauth.client.secret\") + \"&grant_type=refresh_token\\\"\"}",
           "hidden": true
         },
         {
           "name": "$auth_code",
           "description": "Regex that identifies the auth code",
           "shortDescription": "Auth Code Regex",
           "required": false,
           "default": "${auth_code}",
           "hidden": true
         },
         {
           "name": "$access_token",
           "description": "Regex that identifies the access token",
           "shortDescription": "Access Token Regex",
           "required": false,
           "default": "access.[tT]oken",
           "hidden": true
         },
         {
           "name": "$refresh_token",
           "description": "Regex that identifies the refresh token",
           "shortDescription": "Default: refresh.[tT]oken",
           "required": false,
           "default": "refresh.[tT]oken",
           "hidden": true
         },
         {
           "name": "$expiry",
           "description": "Numeric value (in seconds)that specifies the expiry interval or a regex that identifies when the access token expires.",
           "shortDescription": "Default: expires_in",
           "required": false,
           "default": "expires.*",
           "hidden": true
         },
         {
           "name": "$token_type",
           "description": "Regex that identifies the access token type.",
           "shortDescription": "Default: token.?[tT]ype",
           "required": false,
           "default": "token.?[tT]ype",
           "hidden": true
         },
         {
           "name": "accessTokenUsage",
           "description": "Access token usage. A curl type syntax to illustrate how access token should be passed to access a protected resource.",
           "shortDescription": "Default: -H Authorization ${token_type} ${access_token}",
           "required": false,
           "default": "-H Authorization: Bearer ${access_token}",
           "hidden": true
         }
       ]
     },
     "policyInbound": {
       "type": "managed",
       "policy": "HMAC_SIGNATURE_VALIDATION",
       "securityProperties": [
         {
           "name": "signature",
           "hidden": true,
           "required": true,
           "default": "${connectivity::hexDecode(.request.headers.\"x-hub-signature-256\" | split(\"sha256=\")[1])}"
         },
         {
           "name": "signatureString",
           "displayName": "Request Signature Location",
           "hidden": true,
           "required": true,
           "default": "${.request.body}"
         },
         {
           "name": "signatureAlgorithm",
           "displayName": "Request Signature Algorithm",
           "hidden": true,
           "required": true,
           "default": "HMACSHA256"
         },
         {
           "name": "secret",
           "displayName": "Shared Secret",
           "hidden": false,
           "required": true
         },
         {
           "name": "timestampValidator",
           "displayName": "Timestamp Validation",
           "hidden": true,
           "required": false,
           "default": ""
         }
       ]
     }
   }

Here's a sample code that shows the modeling for the JWT_VALIDATION security policy, which Google Cloud Publication Subscription dictates for message validation.

"securityPolicies": [
  {
    "type": "managed",
    "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
    "description": "This policy is used by OIC for invoking GCP Pub/Sub APIs",
    "displayName": "Google Authentication/Authorization Policy",
    "scope": "ACTION",
    "securityProperties": [
      {
        "name": "oauth.client.id",
        "displayName": "Google Client ID",
        "description": "Google Client ID",
        "shortDescription": "Example: 6-jdek24mqqhdleori19r.apps.googleusercontent.com",
        "required": true,
        "hidden": false
      },
      {
        "name": "oauth.client.secret",
        "displayName": "Google Client Secret",
        "description": "Google Client Secret",
        "shortDescription": "Example: GOCDPX-gBQdjksUPXWer4",
        "required": true,
        "hidden": false
      },
      {
        "name": "oauth.access.token.uri",
        "default": "https://oauth2.googleapis.com/token",
        "required": false,
        "hidden": true
      },
      {
        "name": "oauth.scope",
        "default": "https://www.googleapis.com/auth/pubsub",
        "required": false,
        "hidden": true
      },
      {
        "name": "oauth.auth.code.uri",
        "default": "https://accounts.google.com/o/oauth2/auth",
        "required": false,
        "hidden": true
      },
      {
        "name": "clientAuthentication",
        "default": "client_credentials_in_body",
        "required": false,
        "hidden": true
      }
    ],
    "authflow": "flow:extended-oauth"
  },
  {
    "type": "composite",
    "description": "This policy is used by OIC for validating incoming requests as well as for invoking GCP Pub/Sub APIs",
    "displayName": "GCP Pub/Sub security policy",
    "scope": "TRIGGER",
    "policyOutbound": {
      "type": "managed",
      "policy": "OAUTH_AUTHORIZATION_CODE_CREDENTIALS",
      "securityProperties": [
        {
          "name": "oauth.client.id",
          "displayName": "Google Client ID",
          "description": "Google Client ID",
          "shortDescription": "Example: 35532456156-jdek24mdmlqutog3gnc3rfqqhdleori19r.apps.googleusercontent.com",
          "required": true,
          "hidden": false
        },
        {
          "name": "oauth.client.secret",
          "displayName": "Google Client Secret",
          "description": "Google Client Secret",
          "shortDescription": "Example: GOCDPX-gBQdjnPG4Hdi940zJCuksUPXWer4",
          "required": true,
          "hidden": false
        },
        {
          "name": "oauth.access.token.uri",
          "default": "https://oauth2.googleapis.com/token",
          "required": false,
          "hidden": true
        },
        {
          "name": "oauth.scope",
          "default": "https://www.googleapis.com/auth/pubsub",
          "required": false,
          "hidden": true
        },
        {
          "name": "oauth.auth.code.uri",
          "default": "https://accounts.google.com/o/oauth2/auth",
          "required": false,
          "hidden": true
        },
        {
          "name": "clientAuthentication",
          "default": "client_credentials_in_body",
          "required": false,
          "hidden": true
        }
      ]
    },
    "policyInbound": {
        "type": "managed",
        "policy": "JWT_VALIDATION",
        "securityProperties": [
            {
                "name": "subjectClaim",
                "displayName": "Subject claim Override",
                "hidden": true,
                "required": false,
                "default": ""
            },
            {
                "name": "jwtToken",
                "displayName": "JWT Token",
                "hidden": true,
                "required": true,
                "default": "${.request.headers.authorization|split(\" \")|.[1]}"
            },
            {
                "name": "signatureKey",
                "displayName": "JWK URL",
                "hidden": true,
                "required": true,
                "default": "https://www.googleapis.com/oauth2/v3/certs"
            },
            {
                "name": "customClaimsValidation",
                "displayName": "Custom Claims Validation",
                "hidden": true,
                "required": false,
                "default": ""
            }
        ]
    }

Here's a sample code that shows a security policy where the policyInbound section uses the OAuth managed policy, OAUTH_INBOUND. The webhook message authenticates with Oracle Integration similar to how all applications invoke APIs of Oracle Integration.

However, this policy requires a manual setup to initialize the external application with proper credentials, and the external application must obtain the right authentication artifacts.

A bearer token in the header of the webhook message allows Oracle Integration to authenticate the inbound message.

{
    "type": "composite",
    "description": "This policy is used by Oracle Integration to validate incoming requests for Zuora APIs",
    "displayName": "Zuora Composite Security Policy",
    "scope": "TRIGGER",
    "policyOutbound": {
        "type": "managed",
        "policy": "OAUTH2.0_CLIENT_CREDENTIALS",
        "securityProperties": [
            {
                "name": "oauth.client.id",
                "displayName": "Client Id",
                "description": "Used to identify the client(the software requesting an access token) that is making the request. The value passed in this parameter must exactly match the value shown in your API console project.",
                "shortDescription": "Used to identify the client.",
                "required": true,
                "hidden": false
            },
            {
                "name": "oauth.client.secret",
                "displayName": "Client Secret",
                "description": "Used to authorize the client(the software requesting an access token) that is making the request.  The value passed in this parameter must exactly match the value shown in your API console project.",
                "shortDescription": "<unique random string matches your API console project>",
                "required": true,
                "hidden": false
            },
            {
                "name": "oauth.access.token.uri",
                "description": "A request should be sent to this URI for obtaining an access token.",
                "default": "${\"https:/\"+\"/\"+.connectionProperties.invokeHostName + \"/oauth/token\"}",
                "required": true,
                "hidden": true
            },
            {
                "name": "oauth.scope",
                "description": "Permissions your application is requesting on behalf of the user.",
                "shortDescription": "For example: read,write.",
                "default": "",
                "required": false,
                "hidden": true
            },
            {
                "name": "accessTokenRequest",
                "description": "Access Token Request that should be used to fetch the access token",
                "shortDescription": "Example: -X <Method> -H <headers> -d <string-data> <access-token-uri>?<query params>",
                "default": "${\"-X POST -H \" + \"\\\"Content-Type: application/x-www-form-urlencoded\\\" -d \\\"client_id=\" + (.securityProperties.\"oauth.client.id\") + \"&client_secret=\" + ((.securityProperties.\"oauth.client.secret\"|=@uri).securityProperties.\"oauth.client.secret\") + \"&grant_type=client_credentials\\\" \" + \"\\\"https://\" + .connectionProperties.invokeHostName + \"/oauth/token\\\"\"}",
                "required": true,
                "hidden": true
            },
            {
                "name": "refreshTokenRequest",
                "description": "Refresh Token Request that should be used to fetch the access token",
                "shortDescription": "Example: -X <Method> -H <headers> -d <string-data> <refresh-token-uri>?<query params>",
                "required": false,
                "default": "",
                "hidden": true
            },
            {
                "name": "$access_token",
                "description": "Regex that identifies the access token",
                "shortDescription": "Access Token Regex",
                "required": false,
                "default": "access.[tT]oken",
                "hidden": true
            },
            {
                "name": "$refresh_token",
                "description": "Regex that identifies the refresh token",
                "shortDescription": "Default: refresh.[tT]oken",
                "required": false,
                "default": "refresh.[tT]oken",
                "hidden": true
            },
            {
                "name": "$expiry",
                "description": "Numeric value (in seconds)that specifies the expiry interval or a regex that identifies when the access token expires.",
                "shortDescription": "Default: expires_in",
                "required": false,
                "default": "expires.*",
                "hidden": true
            },
            {
                "name": "$token_type",
                "description": "Regex that identifies the access token type.",
                "shortDescription": "Default: token.?[tT]ype",
                "required": false,
                "default": "token.?[tT]ype",
                "hidden": true
            },
            {
                "name": "accessTokenUsage",
                "description": "Access token usage. A curl type syntax to illustrate how access token should be passed to access a protected resource.",
                "shortDescription": "Default: -H Authorization ${token_type} ${access_token}",
                "required": false,
                "default": "-H Authorization: Bearer ${access_token}",
                "hidden": true
            }
        ]
    },
    "policyInbound": {
        "type": "managed",
        "policy": "OAUTH_INBOUND"
    }
}