Table of Contents

Webhooks

Pure Farming uses webhooks to communicate changes in data as that data changes. This allows consumers of data from Pure Farming to react to changes as they occur.

Pure Farming's webhooks are configured using the Ecosystem API. When a webhook is configured, Pure Farming will POST to the configured URL whenever one of the subscribed events occurs.

Important

Web-Hooks are currently disabled, as we are encountering some issues with ensuring successful delivery of messages. At present if you attempt to use any of the endpoints below, you will receive a 501 (Not Implemented) error. In the future this will return to normal service, and this message will be removed.

Endpoints

Endpoint Method Description
/ecosystem/organisations/{OrganisationId}/webhooks GET Get all webhooks for your organisation.
/ecosystem/organisations/{OrganisationId}/webhooks POST Create a new webhook for your organisation.
/ecosystem/organisations/{OrganisationId}/webhooks/{webhookId} GET Get details of an existing webhook.
/ecosystem/organisations/{OrganisationId}/webhooks/{webhookId} DELETE Delete an existing webhook.

For more information about the Ecosystem API, or more detail on the above endpoints see the Ecosystem API Reference.

Tip

See Environments for more information on what the individual URLs are for each environment. The Environments page also contains information about the IP Addresses for each environment so that if necessary you can Whitelist them to allow incoming traffic.

Webhook Registration

In order to create a webhook, you need the following information:

  • Name you want the webhook to have
  • The URL you want Pure Farming to POST events to
  • What kind of authentication your endpoint has (see Authentication for more information)
  • The resource type(s) and / or event types you want to subscribe to

An example payload for creating a webhook could look like:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "Header",
    "headerAuth": {
      "httpHeader": "X-API-Token",
      "apiToken": "abc123--124"
    }
  },
  "subscriptions": [
    {
      "resourceType": "landCoverResource",
      "create": true,
      "update": true,
      "delete": false
    }
  ]
}

In the above example we created a webhook that would be notified when land-cover data (landCoverResource) is created or updated.

Subscriptions

When you create a webhook, you need to provide one or more subscriptions. A subscription should be for either a resource type or a system event.

Property Description
resourceType The Pure Farming resource type to be notified about. See Resource Types for more information.
systemEventType The type of system event you wish to be notified about.
create Whether or not to be notified when a given resourceType has new data or system create event occurs. true if you want to be notified, or false if you don't.
update Whether or not to be notified when a given resourceType has updated data or system update event occurs. true if you want to be notified, or false if you don't.
delete Whether or not to be notified when a given resourceType has data deleted or system delete event occurs. true if you want to be notified, or false if you don't.

Authentication

Pure Farming webhooks support a variety of different authentication methods:

Which authorisation method you need to use will depend on how your endpoint is authenticated, and what you wish to expose to Pure Farming.

See each section for an example of how to register it, and what it could look like in the header of the request to your API.

Best practice is to use OAuth2 Client Credentials flow, as it is secure, and allows credentials to be easily revoked on your side should that be required.

No Authentication

If you set the type of authentication to "None" then Pure Farming will not use any authentication when POSTing events to the provided URL.

To not require any authentication use the following, in your webhook registration:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "None"
  },
  "subscriptions": [ ... ]
}

Basic Authentication

Use Basic Authentication, which will generate an Authorization header like below when POSTing to your provided URL.

POST https://api.exmaple.com/purefarming/webhooks

Authorization: Basic aGVsbG86d29ybGQ=

To set this as your authentication scheme for a webhook registration, use the following:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "Basic",
    "basicAuth": {
      "username": "hello",
      "password": "world"
    }
  },
  "subscriptions": [ ... ]
}

API Token

The Authorization header can be used to pass an API token utilising a custom authorization scheme. This works more or less as follows:

POST https://api.exmaple.com/purefarming/webhooks

Authorization: MyCustomScheme MyCustomToken

To set this as your authentication scheme for a webhook registration, use the following:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "ApiToken",
    "apiTokenAuth": {
      "apiToken": "MyCustomToken",
      "authorizationScheme": "MyCustomScheme"
    }
  },
  "subscriptions": [ ... ]
}

OAuth2 Client Credentials

This is our preferred method of authentication for webhooks, for several reasons:

  1. Security, tokens only last for a short period of time and are not re-used or stored
  2. Revocation of credentials is easy, and entirely possible from your side
  3. Standards based, lots of support and documentation available

When using client credentials, the result is an Authorization header, much like basic or custom API token, but this uses the standard bearer token method:

POST https://api.example.com/purefarming/webhooks

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBMzJub2VqcUcwa3dPOHBUNmhLUFVzRVlLYzh5Q2RXUmp2MGVySHFTQVM0In0.eyJleHAiOjE2OTIwNjU1MjAsImlhdCI6MTY5MjA2NTIyMCwiYXV0aF90aW1lIjoxNjkyMDY1MjE2LCJqdGkiOiI5…

To set this as your authentication scheme for a webhook registration, use the following:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "ClientCredentials",
    "clientCredentialsAuth": {
      "clientId": "pureFarming",
      "clientSecret": "MyReallySecureSecret",
      "tokenEndpoint": "https://auth.example.com/oauth2/token"
    }
  },
  "subscriptions": [ ... ]
}

OAuth2 Authorisation Code

When using authorisation code, the result is an Authorization header, much like basic or custom API token, but this uses the standard bearer token method:

POST https://api.example.com/purefarming/webhooks

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBMzJub2VqcUcwa3dPOHBUNmhLUFVzRVlLYzh5Q2RXUmp2MGVySHFTQVM0In0.eyJleHAiOjE2OTIwNjU1MjAsImlhdCI6MTY5MjA2NTIyMCwiYXV0aF90aW1lIjoxNjkyMDY1MjE2LCJqdGkiOiI5…

The main difference between authorisation code and client credentials flow, is that the assumption here is that you have already completed the authentication flow and have obtained a refresh_token for your authorisation service.
When Pure Farming goes to POST to your endpoint, it first uses the refresh_token to request a new access_token which is then included in the header.

To set this as your authentication scheme for a webhook registration, use the following:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "AuthorisationCode",
    "authorisationCodeAuth": {
      "clientId": "pureFarming",
      "clientSecret": "MyReallySecureSecret",
      "tokenEndpoint": "https://auth.example.com/oauth2/token",
      "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJBMzJub2VqcUcwa3dPOHBUNmhLUFVzRVlLYzh5Q2RXUmp2MGVySHFTQVM0In0.eyJleHAiOjE2OTIwNjU1MjAsImlhdCI6MTY5MjA2NTIyMCwiYXV0aF90aW1lIjoxNjkyMDY1MjE2LCJqdGkiOiI5…"
    }
  },
  "subscriptions": [ ... ]
}

Custom Header

A custom header may be used to provide authorization on your webhook endpoint. This could look as follows:

POST https://api.exmaple.com/purefarming/webhooks

X-API-Token: MyApiToken

To set this as your authentication scheme for a webhook registration, use the following:

{
  "name": "Land-Covers",
  "uri": "https://api.example.com/purefarming/webhooks",
  "authentication": {
    "type": "HttpHeader",
    "headerAuth": {
      "httpHeader": "X-API-Token",
      "apiToken": "MyApiToken"
    }
  },
  "subscriptions": [ ... ]
}

Event Structure

For the payload of our webhooks, we make use of the existing cloudevents standard to provide the events in a standardised format that you can consume. See cloudevents for more information.

For the specification see: JSON Event Format

Example

{
    "specversion" : "1.0",
    "type" : "com.purefarming.landCoverResource.create",
    "source" : "/purefarming/events",
    "id" : "B234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "compurefarmingresourcetype" : "landCoverResource",
    "compurefarmingsystemeventtype" : null,
    "datacontenttype" : "application/json",
    "data" : "{ ... }"
}