🚧

This document covers an in-development feature and may be subject to change

Intro

Webhooks allow developers to be notified via API when changes occur in your Fieldwire projects. They can facilitate building integrations that respond real-time to changes, rather than checking for updates on a pre-determined cadence. Currently, creating and editing webhook subscriptions must also be done via API and will require providing a callback url. The callback URL is a URL that you own that will be the destination for notifications when updates occur in Fieldwire.

This document describes configuring the webhook subscriptions. For more info on the data returned in the webhook payloads please see https://developers.fieldwire.com/docs/webhook-event-types

❗️

Currently each account can only create a max of two subscription.

Authorization using JWT

Unlike other Fieldwire endpoints, the Webhook API uses JWT for authentication rather than API tokens. A JWT is short lived, and must be generated periodically when interacting with the Webhook API, using your API token

see https://jwt.io for more info about JWT

Generating a JWT

To generate your JWT make a POST call to the following url, with your API token provided in the request body

Request body:

URL = "https://client-api.super.fieldwire.com/api_keys/jwt"

body = {"api_token": "<API token>"}

Request (cURL):

curl --location 'client-api.super.fieldwire.com/api_keys/jwt' \
--header 'Content-Type: application/json' \
--data '{
    "api_token": "<API token>"
}'

Response:

Http 201

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUxMiJ9.eyJleHAiOjE2ODI0NDkwNTEsInBheWxvYWQiOnsidXNlcl9pZCI6MiwicHVycG9zZSI6ImFwaWtleSIsInNlc3Npb25faWQiOjF9fQ.aC6xg11c5OKRN-PMRB7ViW1pMueOZS8L3TFfr1bQ3g-wmLoSog4crtk55RqHnZsEEx9ufI2-4XHd1N0DqGdrFf0RuohDDQm5wZb7WYT-L1YK69t_tvDIj1iUqzTnNGEc3EZT4TxwYr2oyfI0hYq047VZBFJRgefDvUIuFlTsX8V6Hzw7CZgPG7ashIOyB9H9iibz8uXctNTn3e5SHqPwz37KnOfVceBVzCtO2tRYBHyqq-AVWdVcDF178tPBXQzql6nGEvwyNiGFlb59xnq355LkSksSU-a_ob44vDx9S0m2wz0q_ml0HUN-evyoQkv_8STcTCyIAnvsDm8ntfaeyqsMXtqvxbZfktYZEhtDgsMvJ14k8LC2gzQLus-9EIeH-_x5DPOINc8rZMqJRGnZrrgB2pLruZ9BkuCnaFC65sp4W4jUB1G8w1AxNT8pMf3HA5Yo5dij_KVCqx9ybVwKU8NChN2x9ubB9O2WQLY7TWMdAe3Ep1LDYfI0J58Xq5goqtHUJWLwEOwWsSP9nx9M2KkiIY4DQD2J0-X6u_3qAswo7_MrVC883cXOth_fYmbRU7wLZaDX_4yPm9_6_X2ajbTLlkfs20QMJnzQrfS7qrMgF0WEYPAiLhk-zZy_mkUF7L2_GoPAIyNvIfFQqRZ-2nKVlq6_HCpmfb4PDriFw1k"
}

Webhook Subscriptions

The webhook subscription is the Fieldwire entity that describes the settings for the notification. See below for details on how to read, create, update and delete webhook subscriptions.

Create Subscription

To create a new subscription send a POST request to the subscriptions endpoint

url = "https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions"

body = 
{
"subscription_name":{{subscription_name}},
"description": {{description}},
"post_url": {{post_url}},
"subscription_status": {{subscription_status}}
}

Field explanations

Note: all properties are required

Example request (cURL)

curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT Token>' \
--data '{
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled"
}'

Response:

Http code 201

{
        "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
        "subscription_name": "Example Webhook Subscription",
        "description": "This is a demo subscription",
        "post_url": "https://Example.com/test",
        "subscription_status": "enabled",
        "account_id": 2
    }

Update Subscription

To update an existing subscription send a PATCH request to the subscriptions endpoint using your subscription ID

url = "https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions/{{subscription_id}}"

body = 
{
"subscription_name":{{subscription_name}},
"description": {{description}},
"post_url": {{post_url}},
"subscription_status": {{subscription_status}}
}

note: any fields can be updated as needed, see above for field explanations

Example request (cURL)

curl --location --request PATCH 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions/<Subscription ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <JWT Token>' \
--data '{
    "subscription_name": "Updated Subscription Name"
}'

Response:

Http response code 202

Get All Subscriptions

To see all subscriptions present on the account, make a GET call to the following endpoint

url = "https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions'
}

Example request (cURL)

curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Bearer Token>'

Response:

Http code 200

An array of json objects

[
  {
        "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
        "subscription_name": "Example Webhook Subscription",
        "description": "This is a demo subscription",
        "post_url": "https://Example.com/test",
        "subscription_status": "enabled",
        "account_id": <Account Id>
    }
]

Delete Subscription

To delete an existing subscription, send a DELETE request to the subscriptions endpoint using your subscription ID

url = "https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions/{{subscription_id}}"

Example request (cURL)

curl --location --request DELETE 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions/<Subscription ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Bearer Token>' \

Response

Http code 202

Get Single Subscription

To see a single subscription, make a GET call to the following endpoint using your subscription ID

url = "https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions/{{subscription_id}}'
}

Example request (cURL)

curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<Account ID>/subscriptions/<Subscription ID>' \
--header 'Authorization: Bearer <Bearer Token'

Response:

Http code 200

A json object that represents a webhook subscription

{
        "subscription_id": "76b770fe-59c3-47a1-b1fa-b2e529a44a6c",
        "subscription_name": "Example Webhook Subscription",
        "description": "This is a demo subscription",
        "post_url": "https://Example.com/test",
        "subscription_status": "enabled",
        "account_id": <Account Id>
    }