{"__v":24,"_id":"5434b7fb008ec22200d86aeb","category":{"__v":2,"_id":"5434b72c008ec22200d86ae7","pages":["5434b7fb008ec22200d86aeb","5434b8ab008ec22200d86af0"],"project":"543469460ef9c00800164f0e","version":"54346a2a0ef9c00800164f28","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-08T04:01:48.238Z","from_sync":false,"order":3,"slug":"webhooks","title":"Webhooks"},"is_link":false,"parentDoc":null,"project":"543469460ef9c00800164f0e","user":"543469060ef9c00800164f01","version":{"__v":7,"_id":"54346a2a0ef9c00800164f28","forked_from":"543469460ef9c00800164f11","project":"543469460ef9c00800164f0e","createdAt":"2014-10-07T22:33:14.982Z","releaseDate":"2014-10-07T22:33:14.982Z","categories":["54346a2b0ef9c00800164f29","543473445b10711400c6c21a","543473500ef9c00800164fde","54347c625b10711400c6c301","5434918d0ef9c008001651ff","5434b72c008ec22200d86ae7","5435990c495d5d0800f3a510"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-08T04:05:15.088Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"Formstack supports [webhooks](http://webhooks.org) which are a way to send form submission data to a specified URL when a form submission occurs. Webhooks can be used in place of or as a supplement to our API. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you need to test your webhooks, we suggest using a service such as [requestb.in](http://requestb.in).\",\n  \"title\": \"Testing Webhooks\"\n}\n[/block]\nWe send the form submission data through an HTTP POST request as either URL encoded form data or as a JSON string depending on the format you select in the webhook configuration options.\n\nWebhooks are configured on a form-by-form basis through the form's Settings tab. To add a webhook to your form, simply select your form from the form dashboard and follow the steps below.\n\n1. Select the **\"Settings\"** tab on the top of the page\n2. Select the **\"Emails & Redirects\"** tab on the left\n3. From the **\"After the form is submitted\"** section, select the **\"Click here to change\"** link\n4. Once the dialog appears, select **\"Send Data to an External URL (WebHook)\"**\n5. Enter your webhook configuration options\n6. Click **\"OK\"** on the dialog and your webhook will automatically save\n\nThe webhook configuration options give you several ways to customize how the data is sent to your webhook's URL.\n\n## Post using field IDs instead of field names\nWhen submission data is sent to your webhook's URL, the keys used to contain each field are the names of the fields you specified when building your form. If you'd prefer these keys to be the numeric ID of the fields, you can select this option.\n\n## Post without sub-field names\nBy default, when Formstack sends data to your webhook's URL, we identify any complex fields such as the Name field or Address field and separate out their subfields. The submission data for a Name Field, for example, will contain at the very least **\"first_name\"** and **\"last_name\"** subfields and may contain more depending on the subfields you selected when building your form. When Formstack sends this data, each subfield is the key of an associative array. If you'd prefer a simple string value such as \"FirstName LastName\", you can select this option.\n\n## Post with field type\nThe submission data being sent to your webhook's URL will always contain the value from the submission for each field on your form. If you'd like to include the field type for each field, you can select this option.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Adding security to your webhooks\"\n}\n[/block]\nIn the webhook configuration options, Formstack allows you to specify a secret key to send along with each request to verify that the request is coming from Formstack. We also send along an HMAC with each request using your secret key so that you can verify that the request body hasn't changed en route to your webhook URL.\n\nThe secret key is included in the submission data as the **\"HandshakeKey\"** field and the HMAC is included in the **\"X-FS-Signature\"** request header.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"FormID\\\": \\\"23534\\\",\\n  \\\"Name\\\": {\\n    \\\"first\\\": \\\"John\\\",\\n    \\\"last\\\": \\\"Smith\\\"\\n  },\\n  \\\"UniqueID\\\": \\\"12345678\\\",\\n  \\\"HandshakeKey\\\": \\\"secretkey\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Request Body\"\n    },\n    {\n      \"code\": \"sha256=909a04cfee970d5c0dda83abb3760c3ee02cde0b9583e72c8d4ff0dd5c2239c2\",\n      \"language\": \"text\",\n      \"name\": \"X-FS-Signature Header\"\n    }\n  ]\n}\n[/block]\nTo validate the request with the signature header value, you will need to encrypt the body of the webhook request with HMAC using the SHA256 hashing function and your shared key.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?php\\n$postdata = file_get_contents(\\\"php://input\\\");\\nlist ($method, $signature) = explode('=', $_SERVER['HTTP_X_FS_SIGNATURE'], 2);\\n\\nif (hash_hmac($method, $postdata, 'secretkey') === $signature) {\\n  // Verified\\n}\",\n      \"language\": \"php\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"webhook-setup","type":"basic","title":"Setup"}
Formstack supports [webhooks](http://webhooks.org) which are a way to send form submission data to a specified URL when a form submission occurs. Webhooks can be used in place of or as a supplement to our API. [block:callout] { "type": "info", "body": "If you need to test your webhooks, we suggest using a service such as [requestb.in](http://requestb.in).", "title": "Testing Webhooks" } [/block] We send the form submission data through an HTTP POST request as either URL encoded form data or as a JSON string depending on the format you select in the webhook configuration options. Webhooks are configured on a form-by-form basis through the form's Settings tab. To add a webhook to your form, simply select your form from the form dashboard and follow the steps below. 1. Select the **"Settings"** tab on the top of the page 2. Select the **"Emails & Redirects"** tab on the left 3. From the **"After the form is submitted"** section, select the **"Click here to change"** link 4. Once the dialog appears, select **"Send Data to an External URL (WebHook)"** 5. Enter your webhook configuration options 6. Click **"OK"** on the dialog and your webhook will automatically save The webhook configuration options give you several ways to customize how the data is sent to your webhook's URL. ## Post using field IDs instead of field names When submission data is sent to your webhook's URL, the keys used to contain each field are the names of the fields you specified when building your form. If you'd prefer these keys to be the numeric ID of the fields, you can select this option. ## Post without sub-field names By default, when Formstack sends data to your webhook's URL, we identify any complex fields such as the Name field or Address field and separate out their subfields. The submission data for a Name Field, for example, will contain at the very least **"first_name"** and **"last_name"** subfields and may contain more depending on the subfields you selected when building your form. When Formstack sends this data, each subfield is the key of an associative array. If you'd prefer a simple string value such as "FirstName LastName", you can select this option. ## Post with field type The submission data being sent to your webhook's URL will always contain the value from the submission for each field on your form. If you'd like to include the field type for each field, you can select this option. [block:api-header] { "type": "basic", "title": "Adding security to your webhooks" } [/block] In the webhook configuration options, Formstack allows you to specify a secret key to send along with each request to verify that the request is coming from Formstack. We also send along an HMAC with each request using your secret key so that you can verify that the request body hasn't changed en route to your webhook URL. The secret key is included in the submission data as the **"HandshakeKey"** field and the HMAC is included in the **"X-FS-Signature"** request header. [block:code] { "codes": [ { "code": "{\n \"FormID\": \"23534\",\n \"Name\": {\n \"first\": \"John\",\n \"last\": \"Smith\"\n },\n \"UniqueID\": \"12345678\",\n \"HandshakeKey\": \"secretkey\"\n}", "language": "json", "name": "Request Body" }, { "code": "sha256=909a04cfee970d5c0dda83abb3760c3ee02cde0b9583e72c8d4ff0dd5c2239c2", "language": "text", "name": "X-FS-Signature Header" } ] } [/block] To validate the request with the signature header value, you will need to encrypt the body of the webhook request with HMAC using the SHA256 hashing function and your shared key. [block:code] { "codes": [ { "code": "<?php\n$postdata = file_get_contents(\"php://input\");\nlist ($method, $signature) = explode('=', $_SERVER['HTTP_X_FS_SIGNATURE'], 2);\n\nif (hash_hmac($method, $postdata, 'secretkey') === $signature) {\n // Verified\n}", "language": "php" } ] } [/block]