Using Webhooks
Easily extend your Slapforms with Webhooks to notify your server whenever someone submits one of your Slapforms.
What are Webhooks
Webhooks are one way that apps can send automated messages or information to other apps. For example, webhooks enable PayPal to communicate with your accounting app when your clients pay you and help WooCommerce to notify you about new orders in Slack. Using the name trigger called slap_webhook, you can forward your form's submission data to any webhook endpoint.
Your webhook endpoint should be ready to receive data as JSON.
If you aren't sure how to set up a webhook, you can learn a few ways here:
- Set up a webhook as a Zapier trigger.
- Set up a webhook as a Firebase Functions trigger.
Make your Slapform execute a Webhook call
Using HTML Forms
Copy-paste this code and just change [email protected] to your own email and https://yourwebsite.com/webhook to your webhook enpoint URL.
<form method="POST"
action="https://api.slapform.com/[email protected]?slap_webhook=https://yourwebsite.com/webhook">
<input type="text" name="name">
<textarea type="text" name="message"></textarea>
<button type="submit">Submit</button>
</form>
Using AJAX Submissions
Don't forget that you can use AJAX to submit forms as well!
Copy-paste this code and just change [email protected] to your own email and https://yourwebsite.com/webhook to your webhook enpoint URL.
<script
src="https://code.jquery.com/jquery-3.2.1.min.js"
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
crossorigin="anonymous"></script>
<script type="text/javascript">
$( document ).ready(function() {
$.ajax({
url: 'https://api.slapform.com/[email protected]?slap_webhook=https://yourwebsite.com/your-webhook-here',
/* replace '[email protected]' with your email and 'https://yourwebsite.com/your-webhook-here' with your Webhook URL*/
dataType: "json",
method: 'POST',
data: {
name: "Jon Snow",
slap_replyto: "[email protected]"
message: "Hello World! This is where the message will go."
},
success: function (response) {
console.log("Response: ", response);
}
});
});
</script>
Pro Tip
It's generally a great idea to use the form inputs for user input and the query string for things set by you. The example above exemplifies this.
Properties of the webhook object
After using the above code to send a webhook to your webhook URL, you need to do something with the data sent!
Below is a table to help you access the properties of the JSON object that is sent via a Sapform webhook.
Meta
| Path | Type | Definition |
|---|---|---|
meta |
object |
This object contains meta data about the response such as the status as well as any errors. |
meta.status |
string |
A string being either success or fail. You can use this to determine whether the submission succeeded or failed. |
meta.errors |
array |
An array of error objects. Each error object has 3 properties: code, type, and msg. You can learn more about what the errors mean in the response error codes. |
meta.referrer |
string |
A string representing the URL of where the form was submitted. |
meta.submission |
number |
The submission count for the period. For example, if it's your 5th submission of the month, this value will be 5. |
meta.submissionId |
number |
The unique submission ID associated with the submission. It will look something like sub_9999-9999-999999999 |
meta.formId |
number |
The unique form ID associated with the form that handled this submission. It will look something like form_99999-9999-9999-9999-99999 |
Data
| Path | Type | Definition |
|---|---|---|
data |
object |
This object contains data that the user submitted. |
data.[name] |
string, number, boolean |
The value of [name] would depend on what data you submitted. For example if you use an HTML form and one of your name attributes is message then you would access it via data.message. |
Triggers
| Path | Type | Definition |
|---|---|---|
triggers |
object |
This object contains data regarding the triggers used in a submission. |
triggers.[name] |
string |
Usually you will not have to use this, but we use it on our hosted submission page to determine how to handle submissions sent with slap_debug. You can access any of the triggers used. To get a full list of the available name triggers, see this page. |
Integrations
| Path | Type | Definition |
|---|---|---|
integrations |
object |
This object contains data regarding the integrations used in a submission. |
integrations.[name] |
string |
Access the properties of the integration object you used on the form, such as integrations.payment. |
Example Webhook Payload
If you have correctly set up your webhook, a Slapform submission will trigger a request to your webhook that will look something like this:
{
"meta": {
"submission": 31,
"sizeBytes": 188,
"sizeNodes": 5,
"requestType": "ajax",
"submissionPeriod": "2019-10-01T00:00:00Z",
"debugMode": false,
"status": "success",
"referrer": "https://yourwebsite.com",
"date": "2019-10-06T19:55:52Z",
"dateUNIX": 1570391752,
"formId": "form_1aa12345-1abc-1234-c456-d1234567890e-0",
"submissionId": "sub_abcdefghik1234567890",
"environment": "production",
"version": 1,
"country": "US",
"ip": "12.34.56.78"
},
"data": {
"name": "Jon Snow",
"message": "Hello World!"
},
"triggers": {
"slap_email": "[email protected]",
"slap_form_id": "0",
"slap_request": "ajax",
"slap_debug": false,
"slap_redirect": "https://yourwebsite.com/thank-you",
"slap_captcha": "true",
"slap_email_format": "table",
"slap_webhook": "https://yourwebsite.com/webhook",
"slap_honey": "",
"slap_replyto": "[email protected]",
"slap_subject": "New Slapform Submission [2019-10-06T19:55:52Z]"
},
"integrations": {
"payment": {
"processor": false
}
}
}
If you want a quick way to test this, please try our Webhook mock tool to send send a test request.