Triggering webhooks

The match and query rule together with and/or rules are flexible enough to solve most complex authorization logic out there. However, in certain edge cases, we need to write custom validation logic. Thats where the webhook rule comes into the picture.

How it works

The basic syntax for the webhook rule is:

{
  "rule": "webhook",
  "url": "<webhook-url>"
}

The webhook rule triggers an HTTP POST request on the url specified in the rule.

The target service performs the custom validation and provides a response accordingly. The webhook rule is resolved only if the webhook target provides a response with status code 2xx. Otherwise the rule is considered rejected and the access is denied.

Request headers

The webhook request made by Space Cloud contains the following headers:

The token is nothing but the token from the client. sc-access-token on the other hand is a token generated by Space Cloud itself, so that the webhook target can verify whether the webhook source is Space Cloud only.

Request body

The request body to the webhook target is a JSON object containing all the variables available inside security rules for that particular operation.

For example, lets say that you are writing a webhook rule for database create operation. The variables available for the database create operation are args.auth, args.token, args.doc. Thus your webhook target in this case would receive a JSON body similar to this:

{
  "args": {
    "auth": {
      ...token claims
    },
    "token": "<some-token>",
    "doc": {
      ...fields of the document to be created
    }
  }
}

Verifying webhook source

As a best practice you should always verify that the incoming webhook request to your service is actually from Space Cloud only and not an intruder.

Space Cloud sends an access token in the headers of each webhook request to do so:

x-sc-token: Bearer <sc-access-token>

The access token is generated by Space Cloud itself with the primary secret provided to it. You can check the primary secret from the Settings page of your project in Mission Control.

The access token contains the following claims:

{
  "id": "<space-cloud-gateway-node-id>",
  "role": "SpaceCloud"
}

To verify whether a webhook is coming from Space Cloud only, you can verify the access token with the primary secret. As an additional security step you can also check the value of role inside the token claims.

Have a technical question?

Improve the docs!