Payload Customization

Overview

Field Nation webhooks support customizable payloads and dynamic URLs, giving you complete control over how webhook data is structured and delivered.

How it works: events with no custom script deliver the standard payload, while events with a custom script are transformed and have any URL templates resolved before delivery.

What You Can Do

Why Customize Payloads?

The Problem

Without customization, integrating with external systems requires:

1. Middleware servers to transform Field Nation's payload format
2. Extra development time to map fields between systems
3. Infrastructure costs to maintain translation services
4. Processing delays from additional network hops

The Solution

With payload customization, transformations happen at the source:

Real-World Use Cases

{
  "u_external_ticket_id": $string($.workorder.id),
  "short_description": $.workorder.title,
  "state": $.workorder.status.name = "Work Done" ? "6" : "2",
  "assignment_group": "Field Services",
  "u_technician": $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name,
  "u_client_company": $.workorder.company.name,
  "work_notes": "Status updated via Field Nation at " & $.timestamp
}

https://api.company.com/{{$.workorder.location.country}}/workorders

{
  "text": "Work Order #" & $string($.workorder.id) & " - " & $.workorder.status.name,
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*" & $.workorder.title & "*\nStatus: " & $.workorder.status.name & "\nTechnician: " & $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name
      }
    }
  ]
}

{
  "WORK_ORDER_ID": $.workorder.id,
  "WORK_ORDER_TITLE": $.workorder.title,
  "COMPANY_NAME": $.workorder.company.name,
  "TECHNICIAN_NAME": $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name,
  "STATUS": $.workorder.status.name
}

{
  "event_type": $.event.name,
  "event_timestamp": $.timestamp,
  "workorder_id": $.workorder.id,
  "company_id": $.workorder.company.id,
  "status": $.workorder.status.name,
  "location_state": $.workorder.location.state
}

Transformation Options

JSONata Expressions (Recommended)

JSONata is a powerful query and transformation language for JSON data.

Basic Field Selection

{
  "order_id": $.workorder.id,
  "title": $.workorder.title,
  "status": $.workorder.status.name
}

Concatenating Fields

{
  "technician_name": $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name,
  "location": $.workorder.location.city & ", " & $.workorder.location.state
}

Conditional Logic

{
  "order_id": $.workorder.id,
  "is_complete": $.workorder.status.name = "Work Done",
  "priority": $.workorder.status.code = "at_risk" ? "high" : "normal"
}

Accessing Arrays

{
  "work_order_id": $.workorder.id,
  "po_number": $.workorder.custom_fields.results.results[name="PO Number"].value,
  "tags": $.workorder.tags.results.label,
  "has_priority_tag": "Priority" in $.workorder.tags.results.label
}

Built-in Functions

{
  "work_order_id": $string($.workorder.id),
  "title_uppercase": $uppercase($.workorder.title),
  "timestamp": $now(),
  "scheduled_date": $substringBefore($.workorder.schedule.service_window.start.utc, " ")
}

Static JSON Merge

For simpler use cases, merge static fields into every webhook payload:

{
  "source": "field-nation",
  "environment": "production",
  "api_version": "3.0",
  "integration_id": "your-integration-id"
}

This adds the static fields to the original payload without transforming it.

Dynamic URL Templates

Include values from the webhook payload in your endpoint URL using template expressions.

Template Syntax

https://api.example.com/workorders/{{$.workorder.id}}/updates

Templates use {{ expression }} syntax where expression is a JSONata path.

Common Patterns

Payload Field Reference

All webhook events include these fields that you can use in transformations:

Root Level

Work Order Core

Company & People

Location

Schedule & Pay

Custom Fields & Tags

Prerequisites

Before customizing payloads, make sure you have:

• An existing webhook, or permission to create one — see Creating Webhooks
• The target payload shape your receiving system expects
• Familiarity with the event's default payload — see Payload Structure
• An OAuth access token, if you configure webhooks via the API — see Prerequisites

Setting Up Payload Customization

{
  "ticket_id": $.workorder.id,
  "title": $.workorder.title,
  "status": $.workorder.status.name,
  "technician": $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name
}

https://api.example.com/workorders/{{$.workorder.id}}

Best Practices

Start Simple

Begin with basic field selection, then add complexity as needed:

// Start here
{ "id": $.workorder.id, "status": $.workorder.status.name }

// Then expand
{
  "id": $.workorder.id,
  "status": $.workorder.status.name,
  "company": $.workorder.company.name,
  "technician": $.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name
}

Handle Missing Fields

Use conditional logic to provide defaults when a field may be absent:

{
  "assignee_name": $.workorder.assignee.user.first_name ? 
    ($.workorder.assignee.user.first_name & " " & $.workorder.assignee.user.last_name) : 
    "Unassigned"
}

Test Before Production

Use the webhook test feature to validate transformations before enabling in production.

Keep Original Payloads

Original payloads are automatically preserved in Field Nation for debugging and re-delivery. You can access them through the delivery logs.

Troubleshooting

API Configuration

Payload customization is configured through the webhookScript object on the webhook resource. Set it when creating a webhook, or add it to an existing one — most teams add it to a webhook that's already running.

Replace YOUR_ACCESS_TOKEN with an OAuth access token — see Prerequisites.

curl -X POST https://api-sandbox.fndev.net/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["workorder.status.work_done"],
    "url": "https://api.example.com/workorders/{{$.workorder.id}}",
    "method": "post",
    "status": "active",
    "webhookScript": {
      "scriptLanguage": "jsonata",
      "script": "{ \"id\": $.workorder.id, \"status\": $.workorder.status.name }",
      "enabled": true
    }
  }'

curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_9f8c3d21 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookScript": {
      "scriptLanguage": "jsonata",
      "script": "{ \"id\": $.workorder.id, \"status\": $.workorder.status.name }",
      "enabled": true
    }
  }'

Get the webhookId (wh_9f8c3d21 above) from the response of the create call, or from List Webhooks.

webhookScript Fields

Additional optional fields (secret, notificationEmail, isIntegrationOnly, webhookAttribute) follow the standard schema — see the Webhooks API Reference.

Summary

Payload customization eliminates the need for middleware by transforming data at the source:

Bottom line: Your webhooks, your format. No middleware required.

Next Steps