Webhooks

Create a webhook

POST/v1/webhooks

Send each new response of a brand, or of one form, to a URL. See Webhook deliveries for the payload, signature and retries.

curl -X POST "$AYEFORM_API/v1/webhooks" \
  -H "Authorization: Bearer $AYEFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brandId": "BRAND_ID",
    "url": "https://luigispizza.com",
    "events": [
      "submission.abandoned"
    ]
  }'

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,
  "secret": "whsec_3f9a…"
}

Body

JSON, with Content-Type: application/json.

brandIdstringrequired
The brand whose responses it receives.
urlstringrequired
The URL deliveries are POSTed to. It must be https://. Plain http:// works only for localhost and 127.0.0.1.
max 2000 chars
eventsarray of enumrequired
The events to receive. submission.completed fires once per response, when the person reaches an ending. submission.abandoned fires once per response when the person gave a valid email, phone or Telegram username and then left without finishing. Leaving means they closed the page or did nothing for 5 minutes. It carries the latest answers, and needs the form's "Save unfinished responses" setting.
1–2 items
formIdstring
Send only this form's responses. Leave it out to send every form of the brand.
activeboolean
Whether the webhook gets new deliveries. Defaults to true.
onlyConsentedboolean
Send only responses where the person agreed to be called and texted, that is consent is agreed. Use it for a buyer who takes only consented leads, on either event. Defaults to false. See Consent.

Response

The webhook with its signing secret. POST /v1/webhooks/{webhookId}/reveal-secret shows it again.

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.
secretstringrequired
The signing secret, starting with whsec_. See Webhook deliveries.

Errors answer with a status and the error shape.