Webhooks

Webhooks are a simple and flexible way to send data from your Particle devices to other apps and services around the Internet. Webhooks bridge the gap between the physical and the digital world, helping you get your data where you need it to be.

You could use a webhook to save valuable information in a database, visualize data being read from a sensor, send the latest weather report to your device, trigger a payment, send a text message, and so much more!

Webhooks with Particle

Webhooks allow you to send data from your connected device anywhere on the Internet

In this guide, we'll provide an overview of how you can use webhooks in your connected products, and walk you through a few examples to get you started.

How webhooks work

Webhooks are tightly integrated with Particle's event system. Devices have the ability to both publish events to the Particle cloud, as well as subscribe to events from the cloud.

A webhook listens for a specific event published by a device. When this event is published, the webhook triggers a web request to a URL on the web. The request sent by the webhook can include information about the event, such as its name as well as any data included when the event was published.

You can configure a webhook to make different types of web requests. The most common type of webhook request is a POST, which is a method of sending data to another web server. In the case of Particle webhooks, this would mean sending data from your devices to a third-party web service. Other types of web requests, like GET and PUT can also be made with webhooks.

Often times, a web server you hit with a webhook will return data to you as a result of the request made. When this happens, your devices can subscribe to a specific event name to receive the response from the web server and use it in your firmware logic.

The combination of webhooks with the Particle cloud's pub/sub event system creates a very efficient way for you to leverage online tools and services and integrate them into your connected product.

Webhooks is one piece of a larger puzzle of Particle Integrations. We want to make it incredibly easy to send data from your devices wherever you need it. In the near future, Particle will offer branded integrations will further simplify the process of sending your data to useful web services.

Your first webhook

Let's get started! For your first webhook, let's try to send some data from your Particle device to a graphing tool. For this example, we'll use ThingSpeak.

Configure ThingSpeak

Create a ThingSpeak account if you don't already have one. Next, create a channel by clicking the "New Channel" button on your ThingSpeak dashboard.

Name your channel "Temperature," add one field called "temp" and create the channel.

Particle ThingSpeak channel

Once you've created the channel, you will need to note the Channel ID as well as your Write API key to use for creating the Particle webhook.

Particle ThingSpeak API Key

Great! We have what we need from ThingSpeak. Now let's go and create the webhook.

Create the webhook

The hub for managing your webhooks is the Particle Console. Log into your console and click on the Integrations tab. If you have created any webhooks in the past, they will appear here. Click on "New Integration" -> "Webhook" to get started.

Integrations Hub

Your Integrations Hub is where you can view and manage Particle webhooks

Let's configure our webhook:

  • Set the event name to temp to match the field in ThingSpeak
  • Set the URL to https://api.thingspeak.com/update
  • Make sure the request type is set to POST (it should be already)
  • If you'd like to limit the webhook triggering to a single one of your devices, choose it from the device dropdown

Next, click on "Advanced Settings," and find "Send Custom Data." Choose "form" from the available options. Drop in the following key/value pairs:

  • api_key: YOUR_API_KEY
  • field1: {{PARTICLE_EVENT_VALUE}}

The form should look something like this:

Thingspeak Webhook

Click the "Create Webhook" button, and boom! You've created your first webhook.

Taking a step back, we now have a webhook listening for the temp event from a Particle device, that will publish temperature data to your ThingSpeak channel. Once the data reaches ThingSpeak, it will be displayed as a line graph.

The last step is getting your Particle device to publish the temp event with some temperature information. For this demo, we'll assume that you don't necessarily have a real temperature sensor, so we'll just generate some random data.

Webhook firmware

To get started, go to Particle Build. Create a new app called "TempWebhook."

Copy/paste the following into your application's code:

int led = D7;  // The on-board LED

void setup() {
  pinMode(led, OUTPUT);
}

void loop() {
  digitalWrite(led, HIGH);   // Turn ON the LED

  String temp = String(random(60, 80));
  Particle.publish("temp", temp, PRIVATE);
  delay(30000);               // Wait for 30 seconds

  digitalWrite(led, LOW);    // Turn OFF the LED
  delay(30000);               // Wait for 30 seconds
}

This code will toggle the on-board LED on and off every 30 seconds. When the LED turns on, the device will generate a random temperature value between 60 and 80 degrees and publish it to the cloud with the event temp. The temperature value is what will be passed on to ThingSpeak and graphed.

Make sure your device is connected and selected in the IDE (Ensure that the appears next to your device in the Devices pane). Flash the code to your device (Click the icon in the sidebar).

Your device should now restart and start publishing the event that will trigger the webhook.

To ensure that everything is working properly, head over to your Logs hub on the console. Every time your webhook triggers, a hook-sent event will appear in your user event stream. If the webhook receives a response from the targeted web server with something in the body, a hook-response event will also appear in your event stream containing the response.

Webhook Logs

hook-sent and hook-response events will appear in your event stream for an active webhook

You should see three types of events appearing in your stream:

  • temp: The original event that your device published that contains the temperature data.
  • hook-sent/temp: Confirmation that the webhook was sent to ThingSpeak's servers.
  • hook-response/temp/0: The response that the webhook received from ThingSpeak. According to ThingSpeak's docs, the response is the entry ID of the update. If the update fails, the response is 0.

Sweet! Things appear to be working properly. Let's check out ThingSpeak and see how our data looks.

See the results

Back on ThingSpeak, navigate back to your channel. You should see temperature data being graphed over time. Your random temperature graph should look something like this:

ThingSpeak Graph

Temperature data from your device being graphed in real-time!

Congratulations! You've created a webhook successfully and gotten data from your connected device into another service. Awesome!

Triggering a webhook

In order to signal to the Particle cloud that the webhook should be triggered, your device must publish an event in its firmware. A webhook that has been configured with the event name temp would trigger with the following firmware:

void loop() {
  // Get some data
  String data = String(10);
  // Trigger the webhook
  Particle.publish("temp", data, PRIVATE);
  // Wait 60 seconds
  delay(60000);
}

Breaking this down:

  • Particle.publish() is the general command for publishing events to the cloud
  • temp is the name of the event that will trigger the webhook
  • data is sent along with the event, which will be included with the webhook's HTTP request
  • PRIVATE ensures that the event will only appear on your private event stream

Getting the response

When using webhooks, it's very common that the targeted web service will return a useful response from the HTTP request containing data that should be sent back to a device. An example of this is triggering a GET request to a weather API, and sending the current weather information back to the device that triggered the webhook.

When a web service target by a webhook returns a response with a body, an event is published back to the event stream in the following format:

# format for hook response events
hook-response/[triggering-event-name]/[index]

Breaking this down:

  • All webhook response event names will begin with hook-response/,
  • Followed by the name of the event that triggered the webhook,
  • And finally a numeric index, as the response body is broken into chunks depending on its size before being published to the event stream

You can then subscribe to this event in firmware, if you'd like a device to have access to the webhook response. A snippet of firmware to get a webhook response can look something like this:

void setup() {
  // Subscribe to the webhook response event
  Particle.subscribe("hook-response/get_temp", myHandler, MY_DEVICES);
}

void myHandler(const char *event, const char *data) {
  // Handle the webhook response
}

In this example, the event that triggered the webhook, get_temp, would result in a webhook response event name of hook-response/get_temp. You don't need to worry about the index when subscribing, as the device will receive all events beginning with hook-response/get_temp. You'll also notice that you'll need a function that will handle the hook-response event. This function will receive the event and its data as arguments.

It is worth mentioning that you can override the default response event name if you'd like. This is useful for product webhooks when you'd like to ensure that only the device that triggered the webhook receives its response. More on that here.

What data gets sent?

When a webhook gets triggered, some data will be sent to the third-party web service by default along with the HTTP request. The default data is:

{
    "event": [event-name],
    "data": [event-data],
    "published_at": [timestamp],
    "coreid": [device-id]
}

This is same data you'd see if you subscribed to your event stream.

These properties will all be strings except for published_at, which is an ISO8601 date formatted string, which tends to be in the form YYYY-MM-DDTHH:mm:ssZ.

You can customize both the type and the structure of data that gets sent with a webhook. To do this, check out the "Send Custom Data" section of the advanced settings when creating a webhook via the console.

Note: Even if you send custom JSON or form data with the webhook, the default data above will still be included in the request. If you do not want this, select "No" under "Include default data" in the advanced settings when creating a webhook.

Monitoring your webhooks

The easiest way to observe webhook activity is on the Logs hub of your Particle Console. Every time your webhook triggers, a hook-sent event will appear in your user event stream. This is confirmation that the Particle cloud successfully forwarded your event to your webhook's target URL.

If the webhook receives a response from the targeted web server with something in the body, a hook-response event will also appear in your event stream containing the response. This event will only appear in your event stream if the web service returned something in the body of its response to the Particle cloud.

Webhook Logs

hook-sent and hook-response events will appear in your event stream for an active webhook

It is also possible that you can see errors appear in your Logs from unsuccessful attempts to contact the third-party server. You can read more about those here.

Note: This method of monitoring activity is not enabled for product-level webhooks. A method for monitoring product-level webhooks is coming soon.

Product webhooks (beta)

If you are building a product using Particle, you now have the ability to create webhooks at the product-level. This will allow you as a product creator to define a single webhook than any of the devices in the product's fleet can trigger.

Product Webhooks

Create a single webhook that any of your product devices can trigger

As devices in your product's fleet will be running the same firmware, product webhooks are a scalable way to integrate with third-party web services. Trigger a product webhook when you'd like to do thing like:

  • Sending information about how a customer's device is behaving to an analytics service
  • Make an API call to your servers to send personalized content to a device
  • Save data to a hosted database in the cloud

Create a product webhook

If you don't have one already, you'll need to define a product before you will be able to create product webhooks. Currently, webhooks for products are in beta and will evolve over the coming months.

Product webhook management can also be done from the Particle Console. To create a webhook, navigate to your product's hub on the console and click on the Integrations tab (). You'll see a very similar view to the Integrations hub as a developer.

Product Integrations Hub

Product integrations are currently in public beta

Click on "New Integration" -> "Webhook." Again, the view will be very similar to what you would see in your developer console. However, you will notice that the "Devices" dropdown has been replaced by a checkbox. This has to do with responses to product webhooks, which we'll cover in the next section.

Create product webhook

Create a product webhook from the Particle Console

Product webhook responses

For product webhooks, because any device in the fleet can trigger the webhook, how can we ensure that only the device that triggers the webhook will receive its response? After all, we wouldn't want a device in Phoenix receiving weather data that another device asked for in Chicago.

This is where the checkbox discussed in the previous section comes into play. The one that says: "Only the device that triggers the webhook should receive its response." This setting (enabled by default) will individualize the webhook response so that it can be routed correctly to the triggering device.

As discussed earlier, any response from a webhook will result in a hook-response/[event_name] event in the event stream. Normally, if you wanted to get that response on your device, you would add something like this to your firmware: Particle.subscribe("hook-response/weather/", myHandler, MY_DEVICES);

If you used this line of code in product firmware, however, a given device listening for a webhook response could receive it from any device in the fleet, not just the webhook that it triggered.

Ensuring that the "Only the device that triggers the webhook should receive its response" checkbox is checked will prepend the device ID of the triggering webhook to the hook-response event. This will allow you to write firmware that will listen to only webhook responses for that particular device, like this:


void setup() {
  // Subscribe to the response event, scoped to webhooks triggered by this device
  Particle.subscribe(System.deviceID() + "/hook-response/weather/", myHandler, MY_DEVICES);
}

void myHandler(const char *event, const char *data) {
  // Handle the webhook response
}

At any time, you can see some sample firmware for both triggering and getting responses from webhooks on your Particle Console. To do this, simply click on one of your product webhooks and scroll down to "Example Device Firmware."

Monitoring Product Webhooks

[Coming Soon]

Advanced Topics

Other ways to manage webhooks

If you prefer not to use the Particle Console, there are other tools you can use to manage webhooks.

If you prefer the command line:

1) The Particle CLI has commands for creating, listing, and deleting webhooks.

If you prefer to manage webhooks programatically:

2) The Particle API has endpoints for creating, listing, retrieving and deleting webhooks.

Webhook variables

A webhook can be configured to inject dynamic data at runtime. The following webhook variables are available for you to use:

  • {{PARTICLE_DEVICE_ID}}: The ID of the device that triggered the webhook
  • {{PARTICLE_EVENT_NAME}}: The name of the event that triggers the webhook
  • {{PARTICLE_EVENT_VALUE}}: The data associated with the webhook event
  • {{PARTICLE_PUBLISHED_AT}}: When the webhook was sent

You can use these variables in a variety of different places when configuring a webhook, such as:

  • Custom JSON or form data sent with the request. This is most commonly used when the web server you are interacting with expects structured data in a specific way. Here's what custom JSON could look like with some webhook variables included:
{
  "source": "{{PARTICLE_DEVICE_ID}}",
  "published_at": "{{PARTICLE_PUBLISHED_AT}}"
}
  • The response topic, or the name of the event that gets sent back to the device with the results of the webhook. You'd want to use webhook variables if you were creating a product webhook that should only return a response to the device that triggered it. Read here for more details.

  • The response template, or the body of data that gets sent back to the device after the webhook has successfully been returned.

Limits

Be a good citizen

Please make sure you have permission from the target site!

Web requests via webhooks can go almost anywhere on the internet, and to almost any service, which is awesome!

In being responsible members of the Internet community, we want to make sure we're not sending unwanted requests to sites, or sending too much traffic, or causing errors. For this reason we ask that you make sure you have permission to make requests to any sites you configure webhooks for, and that you're sending those requests within their usage policies. We will generally disable any hooks, or adjust rate limiting if we hear from site administrators that contact us about issues.

Limits by Host

Any host will be limited to 120 requests per minute unless we're contacted by the site administrator

Particle webhooks will not contact any host more often than 120 times per minute, despite any number of configured webhooks from any number of users. Requests over this limit for the moment will be dropped. We intend to add a proper queuing system so this is done more fairly, but for the moment we've opted to protect sites against abuse first. If you're a site owner / operator and you want to allow more traffic, please email us at hello@particle.io.

Limits by User

You can create up to 20 webhooks, you can send 10 webhooks per minute per device

A user by default may trigger a webook up to 10 times per minute for every device that is registered to their account. A user may create up to 20 webhooks in total.

Note: This means you must have at least one device registered to your account to trigger a webhook.

Error Limits

A webhook will be disabled if the server responds with errors 10 times in a row.

Any webhook that results in an error code from the server (above a 400), 10 consecutive times in a row will be automatically disabled. We'll be adding notifications, and the ability to pause/unpause when this happens, but for the moment you might notice that your webhook stops working for this reason.

Error responses from the target URL will also be sent back in the response event. If you have 10 consecutive errors, the hook will send you a "Too many errors, webhook disabled" message. Make sure you're watching the responses when developing your webhook!

Community Webhook Examples

Below are a few community-written webhook examples. They have been sorted by what they do. These examples were not written by Particle but instead members of our community. Got your own webhook example? Post on the community forums and then issue a pull request to our docs repo.

Sending SMS (Text Messages)

Push Notifications

Sending Emails

Also, check out and join our community forums for advanced help, tutorials, and troubleshooting.