Create Form Hook
/v1/hooks/formorg.permission.hook.createorg.admin.hook.writeThe API key or user must hold at least one of them. Legacy roles still work; prefer the others for new keys.
Creates a form hook.
Creating a form hook will return a new endpoint.
Inbound hooks
An inbound hook is an address that Kustomer hosts for you, either a URL or an email address. Whatever you send to it becomes an event that a workflow can use as its trigger, to create or update customers, conversations or custom objects.
Hooks bring data into Kustomer. They are the opposite of outbound webhooks, where Kustomer sends its events to your URL. You create a hook in Settings › Platform › Inbound webhooks, with these endpoints, or from the hooks section of an app definition. Kustomer returns a unique address (url, or email for email hooks) and an eventName such as kustomer.hooks.web.<id>.receive. A hook doesn't change any data by itself: each request it receives becomes a transaction and fires that event, and a workflow with the hook as its trigger decides what to create or update.
Three kinds of hook
| Form hook | Web hook | Email hook | |
|---|---|---|---|
| Address | POST /v1/hooks/form/{org}/{hash} |
POST /v1/hooks/web/{hash} |
An email address you add as Bcc |
| Authentication | None | An API key with the org.hooks role, as Authorization: Bearer |
None |
| Accepts | JSON, form data (including files) and XML | JSON, form data (including files) and XML | HTML email |
| Best for | Public web forms | Server-to-server integrations where you need to trust the sender | Order and shipping emails you already send |
Form hooks also answer at the older /v1/hooks/form/{hash}, but the {org}/{hash} form is preferred and is the only one that supports reCAPTCHA. Anyone who has a form hook or email hook address can send to it, so validate the data in the workflow. Request bodies are limited to 400 KB; larger ones fail with 413.
For email hooks, Kustomer parses the sender, recipients, subject, bodies and attachments. It also extracts structured JSON from a <script type="application/ld+json"> tag in the HTML, but only when the tag has a data-kustomer-key attribute equal to the hook's key.
Transactions
Every request a hook accepts is stored as a transaction, and the response contains its ID. The transaction is what the workflow trigger receives: your payload is under attributes.data, so workflow steps refer to fields as /#steps.1.attributes.data.<field>.
The transactions endpoints are a debugging aid, not a log of everything received. They only return transactions that arrived while the hook's debug flag was on (set it with PATCH), and each one stays visible for 24 hours.
Which endpoint to use
| To | Call |
|---|---|
| Create a hook | POST /v1/hooks/form, POST /v1/hooks/web or POST /v1/hooks/email |
| List hooks of one kind | GET /v1/hooks/form, GET /v1/hooks/web or GET /v1/hooks/email |
| Read one hook, including its address | GET /v1/hooks/form/{id}, GET /v1/hooks/web/{id} or GET /v1/hooks/email/{id} |
| Rename a hook, or turn debugging on or off | PATCH /v1/hooks/form/{id}, PATCH /v1/hooks/web/{id} or PATCH /v1/hooks/email/{id} |
| Send data to a form hook | POST /v1/hooks/form/{org}/{hash}, or the older POST /v1/hooks/form/{hash} |
| Send data to a web hook | POST /v1/hooks/web/{hash} |
| See what a hook received while debugging | GET /v1/hooks/form/{id}/transactions, GET /v1/hooks/web/{id}/transactions or GET /v1/hooks/email/{id}/transactions |
Use the url or email the API returns exactly as given; don't build it from the hash. Create bodies also accept optional eventName, outputTemplate and outputSchema, the same fields apps use to name a hook's event and shape what workflows receive. Give each system that posts to a web hook its own API key with only the org.hooks role, so a leaked key can't read your data. Hook lists return at most 99 hooks per page.
Request body
application/jsonResponses
Created