Connect HubSpot to a form

Send every submission of a Spillway form to a HubSpot form, so leads land in the CRM with the page and UTM context, while Spillway keeps its own copy.

Before you start: a HubSpot account with a form that accepts external submissions (its portal id and form GUID are in the form's embed code), and a manager account in Spillway (the forms.manage permission).

Steps

1. Forms → New form (or open an existing one). Add the fields you need: at least email of type email, usually name and a message textarea. Note each field's key.
2. Under Connectors add HubSpot. Enter the portal id and form GUID, then map each Spillway field key to the HubSpot property name (email → email, name → firstname, …). Leave a mapping empty to skip that field.
3. Save. Put the form on a page with a Form block whose Form key is the form's key, and publish the page (see Publish a campaign page).
4. Submit the form once from the public page.

Check the result

• Forms → Submissions shows the submission with status Delivered and a hubspot delivery marked ok. A failed delivery shows the error and a Redeliver button; the submission is never lost.
• The contact appears in HubSpot with the mapped properties and, when the visitor's browser had HubSpot's hubspotutk cookie, the usual tracking context.
• GET /api/forms/<id>/submissions returns the same record over the API; GET /api/forms/<id>/submissions.csv exports it.

Notes

• Outbound requests go through the SSRF guard: HubSpot's public endpoint is fine, but a URL on a private network needs SPILLWAY_ALLOW_PRIVATE_URLS=1 (see security.md).
• A Webhook connector (signed with X-Spillway-Signature) and an Email connector (via SMTP_URL) can run next to the HubSpot one.
• Spam protection is built in: a honeypot field, a minimum fill time and a per-address rate limit; see Forms in the API reference.

Going further

• Forms in the getting-started guide.
• Types reference: FormConnector for the exact connector shapes.

Spillway 0.1.0 · Edit this page on GitHub