Start a Camunda Platform 8 Process via REST with Webhooks

Learn how you can use the Camunda Platform 8 REST API to start a process using the latest Connectors.
By
  • Blog
  • >
  • Start a Camunda Platform 8 Process via REST with Webhooks
TOPICS

30 Day Free Trial

Bring together legacy systems, RPA bots, microservices and more with Camunda

Sign Up for Camunda Content

Get the latest on Camunda features, events, top trends, and more.

TRENDING CONTENT

Wondering how you can use the Camunda 8 REST API to start a process? Check out this detailed example and learn how to start a process via the Camunda REST API using the latest Connectors.

Starting a process

To start a deployed process in Camunda Platform 8 you can click some buttons in the user interface on either the Camunda Web Modeler or from Tasklist, or you can do it programmatically using Zeebe’s gRPC API. These options have been around for a while however, and with the recent addition of webhooks to Camunda Platform 8, you’ll now be able to generate an endpoint that, when called, will start a process for you.

Inbound Connectors: Webhooks

Camunda 8 has had Connectors for about a year now. They do things like make REST calls, produce messages for Kafka, send emails through SendGrid and lots more, all without requiring you to code anything. What all of these Connectors have in common is that they’re all outbound. Meaning it’s always the process that is instructing another system to go do some stuff. The latest version of Camunda 8 has added the first inbound Connectors, giving external applications a way of telling the process to do stuff for a change and thus making for a more wholesome relationship between the process engine and external services.

The inbound Connector that’ll help us out in this situation is the Webhook Connector and it’s really easy to get started with it. Once a webhook is set up, it generates a unique URL that an external application or service can use. This URL can be called like you would a REST call in order to start a new process instance.

Creating a Webhook

For this example I decided to lean into the hook element of webhook and create a process to help us find a place to do a spot of fishing.

Creating-webhook

As you can see I want to be able to give the process the name of a fish I’m interested in catching using a REST call, then through the awesome power of DMN, I’ll get a suggested place where I could find that fish.

Once you’ve opened up the Web Modeler, start with a start event that seems appropriate. Once you have that start event you can morph it into a webhook from the context menu.

Selecting-webhook-connector

Now it’s selected, the properties panel will need some info from you, starting with the webhook properties.

Configuring-webhook

As you can see I’ve given it an ID and thrown caution to the wind by disabling authentication. If you’d like to see how the authentication works, feel free to check out this page of the docs. I will not be implementing this here, I don’t feel this example really needs all that much security.

Activating-webhook

Next we have an activation condition. This isn’t required, but I feel I’d like to ensure that only a certified “Fish Person” uses this process, and so once the request comes in it must have a variable called “status” and the value must be “Fish Person”. It’s a watertight way of ensuring we offer this service to true fish people.

Mapping-webhook

Next up we want to get some data from the incoming request. Specifically we’d like to get the name of the fish that the requester would like to find. We do this by parsing the request with FEEL and putting the result into a variable called fish.

You can then build the remainder of the process (or copy it from the GitHub repo) and deploy it to your Camunda 8 cluster. After a successful deployment you can get your hands on the webhook URL by clicking on the tab and copying the link there.

Webhookgen

Before starting the process, you can check it out in Operate.

Operate-view

Just as with other examples making REST calls, we use Postman. To actually start it, you can use Postman to create the following call:

POST https://bru-2.connectors.camunda.io/<your-id>/inbound/FishingSpot

With a body that looks like this:

{"id": 1, 
"status": "Fish Person",
"fish" : "Bass"}

If you send the call you should get back a response like this:

{
    "unauthorizedConnectors": [],
    "unactivatedConnectors": [],
    "executedConnectors": {
        "FishingSpot-FishingExample-4": {
            "type": "START_EVENT",
            "id": "2251799814964011",
            "responseData": {
                "processDefinitionKey": 2251799814964011,
                "bpmnProcessId": "FishingExample",
                "version": 4,
                "processInstanceKey": 2251799814965139
            }
        }
    },
    "errors": []
}

More importantly you should then be able to see a token appear in Operate as well the data produced by the DMN table to help you find the fish you want:

Operate-view-2

In my case I’ve been informed that I can find a Bass either in a river or a supermarket, good to know!

fishingLocations : ["River","Supermarket"]

What’s in the works

This is of course the first iteration, and there are two aspects of this example that are worth keeping an eye on: 1) outbound Connectors and 2) new REST API calls.

More from Outbound Connectors

For the inbound Connectors you can expect to be able to start a process using messages produced by RabbitMQ or Kafka, which is a great addition to the existing ability to send messages to both of those systems using outbound Connectors.

More from Camunda 8 REST APIs

There’s a great community project headed up by our very own Nico Korthout that aims to make available a more extensive REST API for Camunda 8. It’s still in early public beta, but it’s really worth taking a look and getting involved. You’ll find that project here. Why not give your feedback on what APIs you’d most like to see implemented.

Try All Features of Camunda

Related Content

Transition smoothly from design to implementation with an end-to-end business process. We'll show you how!
See how Funding Societies is taking advantage of process orchestration to automate their lending process, greatly improving outcomes for their customers.
Process blueprints can now be found on Camunda marketplace! Read on to learn how they can help you and how you can contribute.