Webhook

Implement the webhook used to approve and provision AWS app credentials in Developer Portal.

What is a webhook?

A webhook is a set of REST endpoints that you, as a Sensedia client, must provide. When a developer requests credentials, the Developer Portal will call this set of REST endpoints. Thus, the developer will be able to access your protected APIs on the Developer Portal.

Below is a summary of the communication flow between Developer Portal and webhook during the credential request:

Step 1

Developer signs up on Developer Portal.

Step 2

Developer goes to the Apps menu and creates a new AWS app (Sensedia API Manager apps do not use webhooks).

Step 3

Developer Portal System makes an HTTP request to the webhook, passing information from the developer's AWS app.

Step 4

Webhook, in your infrastructure, receives the request, creates the credentials, and returns them in the same HTTP request.

Step 5

Developer Portal System receives the return, records the credentials in the database, and provides access to the developer.

Specification

IMPORTANT
It is your responsibility to implement the webhook in your infrastructure, but you can consult an implementation example. The only requirement is to follow the contracts of the REST endpoints to carry out the integration between Developer Portal and webhook.

Open API Specification

To create the webhook, implement the contract below.

Also download the Open API Contract and the Python example.

NOTE
The specification was changed. The optional field customCredentials was added, and it can be used with API KEY and CLIENT CREDENTIALS.

Endpoints

Below are the endpoints you must implement and the details of request and response for each of them.

Action	Endpoint
Create credentials	`POST /v1/createCredentials`
Update credentials	`POST /v1/updateCredentials`
Revoke credentials	`POST /v1/revokeCredentials`
Check availability	`GET /v1/health`

Authentication

All endpoints will use basic authentication. You will receive the header Authorization: Basic <username:password base64> and should validate it as you see fit.

Create credentials

Endpoint responsible for creating and returning the app credentials.

Request

Header:

Body:

Response

Status code: 200 OK
Body:

The response can return either an API Key or Client Credentials.

For credentialType=API_KEY, the fields apiKeyId and apiKey should be returned.

For credentialType=CLIENT_CREDENTIALS, the fields clientId and clientSecret should be returned.

NOTE
The specification of CreateCredentialsResponse was modified. The optional field customCredentials was added to return additional information, such as API KEY and CLIENT CREDENTIALS.

Update credentials

Request

Header:

Body:

Response

HTTP status: 204 No Content
Body: empty

NOTE
The specification of UpdateCredentialsRequest was modified. The optional field customCredentials was added to return additional information, such as API KEY and CLIENT CREDENTIALS.

Revoke credentials

Endpoint responsible for revoking (effectively disabling or deleting) app credentials.

Request

Header:

Body:

Response

Status code: 204 No Content
Body: empty

NOTE
The specification of RevokeCredentialsRequest was modified. The optional field customCredentials was added to return additional information, such as API KEY and CLIENT CREDENTIALS.

Check availability

Application management endpoint. It must return 204 No Content if the request is successful. It may return other status codes like 401, 500 etc.

Request

Header:

Body: empty

Response

Status code: 204 No Content
Body: empty

Error Cases

If the webhook returns any error (status code 4xx or 5xx), the expected message format is:

Webhook implementation example

AWS Lambda

Below is an example of an AWS Lambda, in python, implementing all the endpoints.

IMPORTANT
The code below is just a reference. You should modify it according to your security needs or business rules. The only requirement is to follow the contract defined in the Open API specification.

To download the example, click here.

Creating Credentials

There are two methods for creating credentials:

API Keys

API Keys are generated with the name of the app from the Developer Portal and the email of the developer who created the app.

See the example below:

This method should generate a new key in the AWS console:

And associate it with the Usage Plans:

Client Credentials

Client Credentials are configured by the App Clients of a Cognito User Pool.

See the example below:

This method should create a new App Client:

This app client will have the necessary configurations to generate Client Credentials:

To authenticate APIs using JWT tokens, you must have the authorizer set up in the AWS Gateway and linked to the Cognito user pool.

IMPORTANT
To enable developers to generate tokens, you will need to provide an endpoint giving the client ID and client secret generated during the app creation.

In the example below, a Cognito endpoint is used to generate the token according to the grant-type:

Request

Response

Revoking Credentials

API Keys

See the example below:

This method will delete the API Key from the AWS console.

Client Credentials

See the example below:

This method will delete the app client from the AWS console.

Checking Availability

How happy are you with this page?

Common issues when using AWS Gateway

Developer Portal - Apps