​

Event field mappings

​

1. What a field mapping does

• Inbound unchanged. Ingest and the stored event keep your normalized property names. Mappings never rewrite history.
• Per-destination. The same event can go to HubSpot with email and to a warehouse with email_address — one event, two delivery shapes.
• At dispatch time. The transform runs immediately before the payload is signed and sent. For webhook subscriptions the HMAC signature reflects the post-mapping body, so a verifier on the other side validates what actually arrived.

• Path-to-path renames for event subscriptions and warehouse exports — { "from": "properties.email_address", "to": "properties.email" }.
• Record key-pairs for CRM / ERP object syncs — the destination upsert receives flat records such as { "email": <value>, "FirstName": <value> } built from a source→destination field map plus an upsert identifier field.

​

2. Coverage matrix — where mappings apply today

curl -X GET "https://api.orbit.devotel.io/api/v1/cdp/destination-catalog" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​

3. Where the dashboard stands

​

4. Wire a webhook destination with mappings

curl -X POST "https://api.orbit.devotel.io/api/v1/cdp/subscriptions" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HubSpot contacts webhook",
    "destination": "hubspot",
    "target_url": "https://api.hubapi.com/events/orbit",
    "event_types": ["cdp.event"],
    "policy": {
      "field_redactions": ["properties.internal_note"],
      "field_mappings": [
        { "from": "properties.email_address", "to": "properties.email" },
        { "from": "properties.plan_tier", "to": "properties.plan" }
      ]
    }
  }'

curl -X PATCH "https://api.orbit.devotel.io/api/v1/cdp/subscriptions/sub_cdp_example_123" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "field_mappings": [
        { "from": "properties.order_total", "to": "properties.revenue" }
      ]
    }
  }'

​

5. CRM / ERP object sync field maps

• field_map — source-trait → destination-field pairs. Keys are contact / trait paths on your side; values are the destination API’s field names.
• identifier_field — the destination field the upsert matches on. It must be one of the field_map’s destination values, and two source fields may not map to the same destination field.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/cdp/crm-sync/config/salesforce" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "object_type": "Contact",
    "identifier_field": "Email",
    "segment_id": "seg_high_intent",
    "field_map": {
      "email": "Email",
      "first_name": "FirstName",
      "lifetime_value": "LifetimeValue__c"
    },
    "schedule_minutes": 60
  }'

​

6. Operational notes

• Validation is pair-wise. For object syncs the identifier is validated together with the field map — set field_map before (or with) identifier_field, or the update is rejected.
• Signatures cover the mapped body. Your webhook verifier validates the post-mapping payload, so rotate property names freely without touching verification code.
• Tracking plans stay canonical. Mappings adapt outbound shape only; govern inbound property names with a tracking plan so each destination rename has a stable source.
• Consent gates first. Where a subscription sets a consent channel, the consent check runs before dispatch — a mapped event to a consent-gated destination is still dropped when the contact has no active grant.

​

Related guides

• CDP tracking plan — declare inbound event schemas and triage violations before you map outbound shape.
• CDP reverse ETL to Snowflake and BigQuery — per-table exclude / rename mappings for warehouse exports.
• CDP event debugger and DLQ — inspect delivered and undelivered events when a mapping misroutes a field.
• API reference — CDP endpoints — the generated per-operation shapes for subscriptions, CRM / ERP sync, and the destination catalog.