Webhook Documentation

Webhook Registration Spreadsheet

Information needed to create a webhook:

• 1. Decide/ Ask client what is needed when the form is submitted.  Whether we need a confirmation email, a view submission, or duplication 

  • Note: form duplication not available for forms submitted offline in the app. 

• 2. Register the dev webhook, by first Registering the form in the develop_craft_forms database (there are 2 forms database - dev and prod as of 2/12/25)

• Dev Webhook: https://developformsapi.craft-data.org/webhooks/user-forms

  • in the forms table

    • slug = currently not in use, future human readable that categorizes the form.

    • Label = form title - is what a user might see in a confirmation email. add capitals and spaces

    • Version = not used

    • resource group = is the number associated with each state, ie: 2 is FL, see resource_groups table

    • status id = default is 4

    • created at & updated at = can leave null

    • external id = the xform id string in Kobo form

    • Property maps must include a string that marries the xformid and the submission id

      • minimum content is {"form_uuid": "_xform_id_string", "submission_id": "_id"}

    • sends email = if checked sends email to the resource group admin, AND IF email exists in both the property map AND in the form, sends an email confirmation to someone types into the form.

    • can dupe = if sends email AND is submitted online AND if you have an email in the property map, then you can generate a duplicate button

• **Note: if the email is NOT provided, there is code to send an email to the admin email only (currently craft-data-psa@ncsu.edu). To update this email, it is located in the Resource group admin table.   

• 3. Add the dev webhook to the form

• 4. Update the service account permissions in the Share options. craft_service kobo account should always have all the permissions. 

• 4. TEST the webhook. Locate Submissions of dev webhooks to to the develop_craft_forms database , in the submissions table.

• 5. Update the production webhook, in the craft_forms database to match the dev table add to that the production version of the form. 

**Setting Up an Email confirmation to the Admin

(where there is no form duplication or email in the form)

In the emailsubmissionconfirmationjob.js

Logic: For each resource group admin, within each resource group, for each form, it makes an email that pushes the email out that uses either the resource group admin or another email. As of 2/12/ 25 all resource groups are set to send confirmation emails to craft-data-psa@ncsu.edu

In Develop Craft forms database

1. To assign the admin :

   1. Resource Group admins table: add a line for the resource group of interest pointing to the user of interest (user id) as of 1/16/ 2025 we added resource groups for FL, TX, CA and test

2. Assign an email to the resource group admin table

   1. find the user id number in the users table

   2. go to resource group admin table and add a line for a new resource group (for find the resource group number) and add the user id number

   3. looks like the resource group admin table gets auto-populated…. by form submissions??

   4. anytime an email comes in on a form it gets put in as a new user.

   5. For the dev database we need user 10 and for prod user 94 (because we are searching for an admin email to assign for email confirmations, in this case craft-data-psa@ncsu.edu

3. Register forms with the resource group

   1. in the forms table

More on Webhooks

• editing the form WONT hit the webhook

• will duplicating the form?