Documentation › Service Hooks

Start a process from another tool: service hooks

A hook is an address that another tool calls when something happens: a work item or an issue is created, a message is posted in Teams, an email arrives… SerenForce then finds the right process and automatically starts a process instance, with the title of the item in a variable if you wish. Five tools are supported: Azure DevOps, Jira, Microsoft Teams, Outlook email and Custom (any tool that can send data to an address).

⏱ 5 minutes📍 Service Hooks tab (home page)✅ Prerequisite: a published process

What is a hook for?

How is the process chosen?

The form has two tabs under How is the process chosen?:

1. Create a hook

  1. Click New service hook

    In the Service Hooks tab. The button only shows if you can manage service hooks and see processes.

  2. Integration

    Choose the tool that will call the hook: Azure DevOps, Jira, Microsoft Teams, Outlook email or Custom.

  3. Connection

    As soon as you pick the tool, the Connection section shows the URL to set in it so that its service hook (for example the web hook of Azure DevOps) calls SerenForce, with a button to copy it. For the tools that send a header (Azure DevOps, Teams, Outlook, custom) it also shows the name of the header, X-Hook-Secret. Set the URL in the tool, then save: SerenForce then generates an API key, shown only once, to send in the header X-Hook-Secret. The URL does not change when you save, and the tool you pick changes its address. When you edit a service hook, the same URL is shown with a button to open the connection details.

  4. Details

    Give a Name (required) and, if you wish, a Name of the process instances using the fields received: {Id}, {Type}, {Title}, {Description}, {State}, {Url}, {Tags}, {AreaPath}, {AssignedTo}, {Project}, {Author}. By default the name is {Id} - {Title} for Azure DevOps and Jira, and {Title} for the others.

  5. Manual or AI configuration

    Pick the tab (see How is the process chosen?).

  6. Process

    Choose the published process, who plays each participant and the values of the variables. With Copy a field, a field received fills a variable of the process (the form explains what each field means for the tool). With Add a process, add other processes.

  7. Click Save

    SerenForce shows what to give the other tool: the address and the secret.

2. Connect the other tool

After the creation (or with the Connect to… button of a hook), SerenForce shows the steps for the tool, the URL to call and how to prove who is calling. A tool can send the API key in one of three ways: in the header X-Hook-Secret (the way to prefer), as a bearer token, or at the end of the address (?secret=…, for tools that can only store an address). The API key is shown only once: copy it right away. Lost it? Use Renew the API key: a new API key is shown and the old one stops working.

Azure DevOps

  1. In Azure DevOps

    Open Project settings › Service hooks › Create subscription and choose Web Hooks.

  2. Event

    Choose Work item created (you can filter on the type or the area path).

  3. Address and authentication

    Paste the URL; leave the authentication empty. In HTTP headers, add the header shown followed by the API key, written as X-Hook-Secret: your-api-key.

  4. Test it

    The result of the last call shows on the hook.

Jira

  1. In Jira

    Open Settings › System › WebHooks and choose Create a WebHook.

  2. Event

    Choose Issue created (you can narrow the issues with a JQL query).

  3. Address

    Paste the URL: when the hook has just been created it already holds the API key (?secret=…), because Jira cannot send a header. If the API key is no longer shown, renew it to get the full address.

  4. Test it

    Create an issue: the result of the call shows on the hook. The Number field is the key of the issue (PROJ-12), Area path its first component, Project the key of the project and Author the reporter.

Microsoft Teams

  1. In Teams

    Open Workflows and create a flow from the trigger When a new channel message is added.

  2. Call SerenForce

    Add the action HTTP with the method POST and paste the URL.

  3. Authentication and message

    Add the header shown (X-Hook-Secret) with the API key, and send the message as the body: its text, its sender, its channel and its link.

  4. Test it

    Post a message in the channel. Title is the subject or the first line of the message, Area path the channel, Project the team and Author the sender.

Outlook email

  1. In Power Automate

    Create a flow from the Outlook trigger When a new email arrives (V3); choose the mailbox and, if you wish, filter on the folder, the sender or the subject.

  2. Call SerenForce

    Add the action HTTP with the method POST and paste the URL.

  3. Authentication and email

    Add the header shown (X-Hook-Secret) with the API key, and send the email as the body: subject, body, sender, importance, categories and link.

  4. Test it

    Send yourself an email. Title is the subject, Type the importance (low, normal, high), Tags the categories, Assigned to the first recipient and Author the sender.

Custom

For any other tool that can send data (an HTTP POST with a JSON body) to an address. Since SerenForce cannot know where each piece of information is in what the tool sends, you tell it in the section Where are the fields? of the form: for each field, the path in the JSON, for example issue.key or items[0].title. Fill in at least one path and leave the others empty.

  1. In your tool

    Send a POST request with the JSON of the event to the URL each time something happens.

  2. Authentication

    Add the header shown (X-Hook-Secret) with the API key, or use a bearer token.

  3. Test it

    The result of the last call shows on the hook; check that the paths find their values.

3. Follow and manage your hooks

The Service Hooks page lists your service hooks: their tool, how they choose, their processes, their state (Active or Paused), the last call and its result:

Good to know

Permissions