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.

If you are looking for all the juicy details, head over to the webhook reference page.

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() {

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

  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

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

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);

  // 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


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);

  // 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]

Debugging with RequestBin

Depending on the service you're sending data to, it can be difficult to debug a webhook, especially if you're using sending data using templates. A great debugging tool is the free service http://requestb.in/. You create a new RequestBin and it returns a URL that you use as the URL in your webhook. Then, when you refresh you RequestBin page, it will show you the requests that have come in, with all of the parameters and data. Very handy!

Here's a simple webhook JSON file. Save it in a file "hook1.json".

    "event": "test1",
    "url": "http://requestb.in/19le9w61",
    "requestType": "POST",

You can create a webhook using the Particle CLI by issuing the command:

particle webhook create hook1.json

Tested it first using the CLI:

particle publish test1 "testing" --private

And this is what the request bin looks like:

Request Bin Example

In this simple example, you can see the POST request with the default data in form encoding.

Here's an example using JSON encoding.

    "event": "test1",
    "requestType": "POST",
    "json": {
        "name": "",
        "value": ""
    "noDefaults": true

Generating the event:

particle publish test1 "testing2" --private

And the RequestBin results: Request Bin Example

Advanced Topics

See the webhook reference for more details on customizing webhooks with variables, examples of different webhook configurations as well as community guides on setting up webhooks with external services.

As a quick reference, these are the pre-defined webhook variables 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

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