Webhooks

With Reform's webhooks, you can connect Reform to all the other tools and services you use.

Creating a form webhook

To create a new webhook for one of your forms, navigate to the Integrations page in Reform. Toggle the webhook integration and paste in the URL you want Reform to send the webhook to.

Now, every time a new event happens (such as a new form submission), Reform will send a webhook to the URLs in the Active webhooks list.

Securing webhooks

When Reform sends a webhook it includes a Signature header. The header contains a SHA-265 HMAC signature of the request using a secret unique to the webhook. This can be used to verify that the payload has not been altered by a third party.

First you need to find the webhooks secret. Open the Reform dashboard, go to your form, go to 'Integrations', go to the 'Webhook' integration settings, locate your webhook and click on the 'lock' icon.

When you recieve a webhook you need to do the following:

Read the Signature header
Read the request body
Generate a SHA-256 HMAC signature using the request body and the webhook secret
Compare the signature from the request header with the signature you created

Here is a PHP example:

$request = [
  'headers' => [
    'Signature' => '974dad6fada1c0f935438bab0d6b7f087bec84ebb68be6b65c945bc85c83bb7e',
    // ... More headers here
  ],
  'body' => [
    'type' => 'form.submitted',
    'id' => 'd61a336b-2493-438b-a901-fc2efab7766b',
    'occurred_at' => '2022-11-29T11:05:56+00:00',
    'payload' => [
      'form' => [
        'id' => '767ab2ea-9d80-4eee-82c7-db8a984282ea',
        'created_at' => '2022-11-29T10:22:57+00:00',
        'name' => 'Webhook form',
        'status' => 'published',
        'link' => 'https://forms.reform.test/kfFeHt/untitled-form'
      ],
      'submission' => [
        'id' => '8f1d6860-271c-40db-afd1-3d75d0d8c61a',
        'created_at' => '2022-11-29T11:05:56+00:00',
        'answers' => [
          'a49be7cf-8bfc-426c-a006-fde58fbb851c' => [
            'id' => '86e2abde-7ea9-43fd-aa04-bbbe1dca584c',
            'question' => 'What is your name?',
            'answer' => 'qqq'
          ]
        ]
      ]
    ]
  ],
];


$secret = 'zpLTNyPsWXcMw7JfZUQx8tWSNXR61dRcTfS6Hl3N'; // Fetched from the Reform dashboard
$signature = $request['headers']['Signature'];
$body = json_encode($request['body']);
$signedBody = hash_hmac('sha256', $body, $secret);


if ($signedBody === $signature) {
  // Request is valid
} else {
  // Validation failed
}

Event types

form.submitted

The form.submitted event occurs every time someone submits a form. Each key in the answers list is the unique ID for the answer. By using the ID to refer to an answer when consuming the webhook, you don't need to rely on the order of the questions to always be the same.

The webhook payload looks like this:

{
  "type": "form.submitted",
  "id": "e37e6e48-fceb-4cba-9404-1ae6aabcea3f",
  "occurred_at": "2021-05-25T04:56:26+00:00",
  "payload": {
    "form": {
      "id": "bbe7930f-04cd-4b0d-b858-7c7cf1b5a86f",
      "created_at": "2021-05-25T04:53:12+00:00",
      "name": "Breakfast survey"
      "link": "https://forms.reform.app/W8eMHb/zUC012"
    },
    "submission": {
      "id": "8d68278b-046d-4692-93df-3126e7a122ca",
      "created_at": "2021-05-25T04:56:26+00:00",
      "answers": {
        "7f5b0169-0ae0-4256-929b-262c3f38af40": {
          "id": "f98665cb-05e8-452b-a746-05fd026b06bc",
          "question": "What's your name?",
          "answer": "Peter Suhm"
        },
        "5016fd53-f3e8-4ea1-9d79-66cc4e592adf": {
          "id": "b1a6f197-76b9-4387-9168-967a5dec4237",
          "question": "What's your email?",
          "answer": "[email protected]"
        },
        "0a1c6425-67ed-4e29-ba76-a4f003f6d0a2": {
          "id": "44a7c70e-bfee-4dbd-a762-49c85839ec03",
          "question": "What did you have for breakfast?",
          "answer": "A fried egg"
        }
      }
    }
  }
}