Webhook events and payloads

Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

• X-Fluid-Hook-Guid: The unique identifier of this webhook configuration.
• X-Fluid-Event: The name of the event that triggered the delivery.
• X-Fluid-Entity: The name of the entity this event was triggered.
• X-Fluid-Delivery: A globally unique identifier (GUID) to identify the delivery.
• X-Hub-Signature-256: This header is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key. For more information, see Validating Webhooks
• User-Agent: This header will always have the prefix Fluid-Hookshot/{WebhookIntegrationName} where WebhookIntegrationName  is the value as configured by the client. when setting up this Webhhook.
• X-Fluid-Hook-Principal-Entity: The type of entity where the webhook was created. For an Action this value would be the principal entity of this Action, ie "Board".
• X-Fluid-Hook-Principal-Guid: The unique identifier of the entity where the ok was created. For an Action this would be the principal Guid, which is the unique Board Guid.

Example webhook delivery

You can choose to have payloads delivered in JSON format (application/json) Following is an example of a webhook POST request that uses the JSON format for an Action.

{
  "event": "Create",
  "entityType": "Action",
  "entity": {
    "fields": {
      "assignee": null,
      "attachmentCount": 0,
      "author": {
        "id": 603,
        "guid": "f1cb6467-0262-4539-9148-7b869defd817",
        "name": "David Burt",
        "userName": "david.burt",
        "email": "david.burt@fluidbsg.com"
      },
      "boardCategory": 0,
      "boardId": 0,
      "boardGuid": "89f97f10-6bbd-4f75-8cf6-ad0fb9d6f3a0",
      "boardTitle": "Agile T1",
      "businessValue": 0,
      "chatCount": 0,
      "contentType": "Process",
      "createDate": "2024-03-22T13:14:49.0000000",
      "description": "",
      "descriptionHtml": null,
      "dueDate": null,
      "endDate": null,
      "impediment": 0,
      "isClosed": false,
      "isCalculated": false,
      "isOwner": true,
      "modifiedBy": {
        "id": 603,
        "guid": "f1cb6467-0262-4539-9148-7b869defd817",
        "name": "David Burt",
        "userName": "david.burt",
        "email": "david.burt@fluidbsg.com"
      },
      "modifiedDate": "2024-03-22T13:14:49.0000000",
      "points": 1,
      "parentGuid": "3d3a4acf-193e-424b-a61d-856d83728ba3",
      "priority": "Medium",
      "principalGuid": "89f97f10-6bbd-4f75-8cf6-ad0fb9d6f3a0",
      "shortCode": "AT-85",
      "startDate": null,
      "status": "Not Started",
      "statusCode": 1,
      "taskType": "Task",
      "title": "r",
      "titleRichText": "r",
      "titleHtml": "r"
    },
    "id": 4566,
    "guid": "6dfb56bc-91ab-4739-a95e-ad508c2ac206",
    "url": "https://localhost:62199/rest/api/action/4566"
  }
}

Note: In this example the entity property of the event payload is the same entity JSON model that is used for the REST API for Actions see Fluid REST API Reference for more details. Webhook JSON entity models will always match the REST API JSON models.

Definitions

Entity

Depending on the webhook entity type, eg, Action WebHook the entity property represents the entities full state at the time the webhook was triggered.. In this example see Get Action REST API call for full details.