Webhooks

Set a posting spec

POST/v1/webhooks/{webhookId}/posting-spec

Make a form webhook post each lead in a buyer's own format, replacing any spec it had. Only a webhook for one form can have a spec. Others get 400 posting_spec_needs_form. See Posting in a buyer's format.

curl -X POST "$AYEFORM_API/v1/webhooks/$WEBHOOK_ID/posting-spec" \
  -H "Authorization: Bearer $AYEFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "format": "json",
      "entries": [
        {
          "key": "…",
          "value": {
            "kind": "field",
            "fieldId": "FIELD_ID"
          }
        }
      ]
    }
  }'

200 Response

{
  "id": "0x4ppa92sn45th2skcfhp95keyz4x3c1",
  "brandId": "khs69yxwyr7kw03m5j1v7qmhdvknj6ac",
  "formId": "v7wskeddca2z4gmve1gy0vfpx75gt60p",
  "url": "https://luigispizza.com",
  "events": [
    "submission.abandoned"
  ],
  "active": true,
  "createdAt": 1790879400000,
  "postingSpec": {
    "format": "json",
    "entries": [
      {
        "key": "fk_live_…",
        "value": {
          "kind": "field",
          "fieldId": "y7ewwzttjnavxq96ctvtn0mg52c91jey",
          "part": "first"
        },
        "format": "phoneDigits"
      }
    ],
    "headers": [
      {
        "name": "Luigi's Pizza"
      }
    ],
    "warnings": [
      {
        "index": 1,
        "key": "fk_live_…",
        "message": "…"
      }
    ]
  },
  "onlyConsented": false
}

Path parameters

webhookIdstringrequired
The webhook's id.

Body

JSON, with Content-Type: application/json.

specobjectrequired
The format, the body's keys in order, and extra headers.
Show 3 fieldsHide 3 fields
- formatenumrequired
  How the body is encoded. "json" sends application/json and "form" sends application/x-www-form-urlencoded.
  One of "json", "form"
- entriesarray of objectrequired
  The body's keys, in order. The body holds exactly these keys. As JSON, it is a flat object of strings.
  1–200 items
  Show 3 fieldsHide 3 fields
  keystringrequired
  The key in the body, exactly as the buyer names it.
  1–200 chars
  valueone of 3required
  What to send under the key. Every value is sent as a string.
  Show 3 optionsHide 3 options
  kind: "field"
  kind"field"required
  A question's answer. Lists are joined with commas and files are sent as their links. A question that's gone or wasn't answered sends an empty string.
  fieldIdstringrequired
  A question's id in the form's definition.
  1–100 chars
  partenum
  One part of the answer. For a name question, first or last. For an address question, line1, line2, city, state, zip or country. state is the region, such as a state, province or county. zip is the postal code. country is the ISO 3166-1 alpha-2 code. Leave it out to send the whole answer. A whole address is one line, written the way its country writes addresses, with the country's name.
  One of "first", "last", "line1", "line2", "city", "state", "zip", "country"
  kind: "meta"
  kind"meta"required
  A contact or tracking value.
  sourceenumrequired
  Which value to send. trustedFormCertUrl is the response's TrustedForm certificate URL. It is empty until responses carry one. consent is yes when the person agreed to be called and texted and no otherwise. consentAt is when they agreed, and consentText the wording they agreed to. Both are empty unless they agreed. phoneVerified is yes when the number was verified with a texted code, separate from consent.
  One of "email", "phone", "fullName", "firstName", "lastName", "ip", "userAgent", "pageUrl", "submittedAt", "responseId", "formName", "jornayaLeadId", "trustedFormCertUrl", "consent", "consentAt", "consentText", "phoneVerified"
  kind: "constant"
  kind"constant"required
  The same text on every lead.
  valuestringrequired
  max 2000 chars
  formatenum
  How to write the value. For phones, phoneDigits gives just the digits, without the +1 for US and Canada numbers and with the country code for others. phoneE164 gives E.164, and phoneUs gives (415) 555-0123. For dates, submittedAt and consentAt, dateIso gives YYYY-MM-DD and dateUs gives MM/DD/YYYY. For yes/no values, such as consent, a yes/no question or a consent question, boolTrueFalse gives true or false, boolOneZero gives 1 or 0, and boolYN gives Y or N. Leave it out to send the value as stored. Constants ignore it.
  One of "phoneDigits", "phoneE164", "phoneUs", "dateIso", "dateUs", "boolTrueFalse", "boolOneZero", "boolYN"
- headersarray of object
  Extra headers to send, such as the buyer's API key. They go alongside Forms-Event, Forms-Delivery and Forms-Signature. Header values are never returned.
  max 20 items
  Show 2 fieldsHide 2 fields
  namestringrequired
  1–100 chars
  valuestring
  The header's value. Leave it out to keep the saved value. Header values are never returned.
  max 2000 chars

Response

idstringrequired
The webhook's id.
brandIdstringrequired
The brand it belongs to.
formIdstring or nullrequired
The one form it delivers for. Null means every form of the brand.
urlstringrequired
Where deliveries are POSTed.
eventsarray of enumrequired
The events it receives.
activebooleanrequired
Whether it gets new deliveries. An inactive webhook gets none.
createdAtnumberrequired
When it was made, in milliseconds since the epoch.
postingSpecone of 2required
How it posts in a buyer's own format. Null means it sends the standard JSON payload.
Show 2 optionsHide 2 options
- Option 1
  - formatenumrequired
    How the body is encoded. "json" sends a flat JSON object of strings, and "form" sends it form-encoded.
    One of "json", "form"
  - entriesarray of objectrequired
    The body's keys, in order.
    Show 3 fieldsHide 3 fields
    keystringrequired
    The key in the body, exactly as the buyer names it.
    1–200 chars
    valueone of 3required
    What to send under the key. Every value is sent as a string.
    Show 3 optionsHide 3 options
    kind: "field"
    kind"field"required
    A question's answer. Lists are joined with commas and files are sent as their links. A question that's gone or wasn't answered sends an empty string.
    fieldIdstringrequired
    A question's id in the form's definition.
    1–100 chars
    partenum
    One part of the answer. For a name question, first or last. For an address question, line1, line2, city, state, zip or country. state is the region, such as a state, province or county. zip is the postal code. country is the ISO 3166-1 alpha-2 code. Leave it out to send the whole answer. A whole address is one line, written the way its country writes addresses, with the country's name.
    One of "first", "last", "line1", "line2", "city", "state", "zip", "country"
    kind: "meta"
    kind"meta"required
    A contact or tracking value.
    sourceenumrequired
    Which value to send. trustedFormCertUrl is the response's TrustedForm certificate URL. It is empty until responses carry one. consent is yes when the person agreed to be called and texted and no otherwise. consentAt is when they agreed, and consentText the wording they agreed to. Both are empty unless they agreed. phoneVerified is yes when the number was verified with a texted code, separate from consent.
    One of "email", "phone", "fullName", "firstName", "lastName", "ip", "userAgent", "pageUrl", "submittedAt", "responseId", "formName", "jornayaLeadId", "trustedFormCertUrl", "consent", "consentAt", "consentText", "phoneVerified"
    kind: "constant"
    kind"constant"required
    The same text on every lead.
    valuestringrequired
    max 2000 chars
    formatenum
    How to write the value. For phones, phoneDigits gives just the digits, without the +1 for US and Canada numbers and with the country code for others. phoneE164 gives E.164, and phoneUs gives (415) 555-0123. For dates, submittedAt and consentAt, dateIso gives YYYY-MM-DD and dateUs gives MM/DD/YYYY. For yes/no values, such as consent, a yes/no question or a consent question, boolTrueFalse gives true or false, boolOneZero gives 1 or 0, and boolYN gives Y or N. Leave it out to send the value as stored. Constants ignore it.
    One of "phoneDigits", "phoneE164", "phoneUs", "dateIso", "dateUs", "boolTrueFalse", "boolOneZero", "boolYN"
  - headersarray of objectrequired
    The extra headers' names. Values are never returned.
    Show 1 fieldHide 1 field
    namestringrequired
  - warningsarray of objectrequired
    Entries to check against the form's current questions, such as one whose question is gone. Such an entry sends an empty string.
    Show 3 fieldsHide 3 fields
    indexnumberrequired
    The entry's position in entries.
    keystringrequired
    The entry's key.
    messagestringrequired
    What to check, in plain words.
- null
onlyConsentedbooleanrequired
Whether it sends only responses where the person agreed to be called and texted.

Errors answer with a status and the error shape.