Processing Flow

This page describes the end-to-end flow when a Formidable Forms webhook is received, from authentication through record creation.

Flow Diagram

flowchart TD A[Webhook received] --> B{Bearer token valid?} B -- No --> B1[401 Unauthorized] B -- Yes --> C{Integration enabled?} C -- No --> C1[200 OK — disabled] C -- Yes --> D[Fetch entry from Formidable REST API] D -- Failure --> D1[502 — notify formidable_api_error] D -- Success --> E[Extract form values] E --> F{Form mapping exists?} F -- No --> F1[200 OK — no mapping] F -- Yes --> G[Geo-lookup IP via ipstack] G --> H{Country banned?} H -- Yes --> H1[Assign to admin user] H -- No --> H2[Weighted random lead assignment] H1 --> I[Search Pipedrive by email] H2 --> I I --> J{Person found?} J -- Yes --> K{Has open deal?} J -- No --> P[Create person + Create deal] K -- Yes --> L[Update person + Update deal] K -- No --> M{Has closed deal in inactive pipeline?} M -- Yes --> N[Update person + Update deal] M -- No --> O{Person has no deals?} O -- Yes --> Q[Update person + Create deal] O -- No --> L L --> R[Twilio phone enrichment — optional] N --> R P --> R Q --> R R --> S[Create note on deal] S --> T[200 OK — success]

Step-by-Step

1. Authentication

The server validates the Authorization: Bearer <token> header against the stored formidableWebhookSecret for the company. If no secret is configured, authentication is skipped (open endpoint).

2. Automation User Resolution

The handler resolves the automation user’s Pipedrive OAuth token via getAutomationToken(). If the automation user is not configured or the token cannot be refreshed, the webhook fails with a 503 and a notification is sent.

3. Entry Fetch

The server calls the Formidable REST API (GET /wp-json/frm/v2/entries/:id?show_fields=true) to retrieve the full entry data. The webhook payload itself only contains form_id, entry_id, and ip_address.

4. Form Mapping Lookup

The form_id is matched against the configured field mappings (formidableFieldMaps). If no mapping exists for the form, the webhook returns successfully with a “no mapping” message.

5. Geo-Blocking Check

If an ipstack API key is configured, the submitter’s IP address is looked up. If the resolved country code appears in the bannedCountries list, the lead is flagged as geo-blocked and assigned to the admin user instead of going through weighted random assignment.

6. Duplicate Detection

The server searches Pipedrive for existing persons by email using the v2 API (/persons/search). Match priority:

  1. Newest open deal in any pipeline — update that person and deal.
  2. Newest closed/lost deal in the inactive pipeline — update that person and deal (returning contact).
  3. Person with no deals (lowest ID) — update person, create a new deal.
  4. No person found — create both person and deal.

7. Person Upsert

A person payload is built from the field mapping. For existing persons, the server sends a PATCH to preserve existing data. For new persons, a POST creates the record. Email and phone values are de-duplicated against existing values on the person.

8. Deal Upsert

A deal payload is built from the field mapping. New deals are assigned to the configured pipeline’s first stage and titled with the person’s name. Existing deals are updated in place. Enum fields are resolved through optional enumMap overrides.

9. Twilio Phone Enrichment (Optional)

If Twilio credentials are configured, the server calls the Twilio Lookups v2 API to format the phone number in E.164 and determine the line type (mobile, landline, VoIP). The line type is used to set the phone label (Mobile or Home).

10. Note Creation

If the form mapping includes noteFields, an HTML note is created on the deal containing the specified field labels and values.

All Pipedrive API errors during person or deal writes trigger a formidable_pipedrive_error notification. Enable this category in General settings to receive email alerts when submissions fail to write to Pipedrive.

Previous Field Mapping Next Overview