🚧

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
• For info on how to use Event filters please see https://developers.fieldwire.com/docs/webhook-event-filters

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.

note: You may see some subscriptions set with an internal: true flag. These are subscriptions that are automatically generated by the Fieldwire platform for various integrations. These webhook subscriptions cannot be edited and do not count against your webhook subscription limit.

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}},
	"entity_filters": [{{Entity.Action}}],
   "project_filters": [{{Project_ids}}]
}

Field explanations

Note: not 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 <access_token>' \
  --data '{
    "subscription_name": "Example Webhook Subscription",
    "description": "This is a demo subscription",
    "post_url": "https://Example.com/test",
    "subscription_status": "enabled"
  }'

Note: only required fields are shown

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": "<account_id>",
  "internal": false,
  "entity_filters": [],
	"project_filters": []
}

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 <access_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

Example request (cURL)

curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/{{account_id}}/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <access_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>",
    "internal": false,
    "entity_filters": [],
    "project_filters": [],
  }
]

Delete Subscription

To delete an existing subscription, send a DELETE request to the subscriptions endpoint using your 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 <access_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

Example request (cURL)

curl --location 'https://webhook-api.us.fieldwire.com/webhook/account/<account_id>/subscriptions/<subscription_id>' \
  --header 'Authorization: Bearer <access_token>'

Response:

{
  "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>",
  "internal": false,
  "entity_filters": [],
	"project_filters": [],
}

Regionalization

Note that similar to the core API, the Fieldwire webhook api is regionalized. Currently there are two supported regions:

US: webhook-api.us.fieldwire.com

EU: webhook-api.eu.fieldwire.com