Before you start
You must be a workspace admin to create a webhook from a form
The external system sending the webhook must be able to supply an ID for an employee that matches their HRIS ID supplied to Pyn
Webhooks are attached to forms, which you can create with the instructions in https://intercom.help/pyn/en/articles/16857779-create-and-use-forms-pyn-2
Currently Pyn only accepts a single submission per employee per form through a webhook
Webhooks submissions are "all-or-nothing": all required fields must be submitted and valid to be recorded
Add the webhook
Navigate to the form you want to convert into a webhook through Flows -> Forms -> [Your form name]
Open the Settings panel (cog icon) on the right hand tools menu, and press Add Webhook
Select the source system that your external system will send in the Subject dropdown
Note down the URL and the supplied POST body to be used by your sending system
Mint a secret by pressing Create Secret. This secret will only be displayed once, so note it down.
Frequently asked questions
How can I test the webhook?
Pyn can provision a sandbox workspace that you can use to test the webhook without impacting your production Pyn workspace.
How can I rotate the secret?
A new secret can be minted at any time by pressing Replace Secret. The old secret will be revoked immediately.
What HTTP responses could my webhook receive?
Pyn will respond with the following status codes:
202: The request was was received successfully. This does not guarantee that the underlying form submission succeeded
400: The request was unparsable
404: The webhook could not be found, was archived, or a valid bearer secret was not supplied
500: Pyn systems failed while trying to receive the webhook. This can be retried
How can I troubleshoot any issues?
If a webhook request returns a non-202 response, check the above section for more information on how to resolve that specific error code.
Pyn processes webhooks asynchronously, so a 202 response means that Pyn has successfully received the webhook, but not that the underlying form submission succeeded. The webhook logs for the given form will show the successful and failing submissions.