How do webhooks work on Outlaw? – Outlaw

Webhooks Overview

Webhooks give you the ability to be notified of important events that occur in Outlaw. Once configured, when an event is triggered your application will be sent an HTTP/HTTPS request containing information related to the event. This allows your app to react immediately and handle relevant events in realtime.

Supported Events

These are the events that are currently supported by webhooks. Each event can be further classified by event actions.

Event: Deal Status

This event will be triggered when a deal is updated to a certain status. Below are the event actions:

Create - When a new deal is created.
Delete - When a deal is deleted.
Done - When a deal is complete. This supports custom workflows as well and will trigger on the last step of a workflow.
Status Change - When a deal status changes. This includes deal creation.

How to Configure Webhooks in Outlaw

Webhooks are configured for each team. To enable webhooks and start configuring, navigate to the Team page and click on the "Integrations" tab.

Step 1: Enable webhooks. In order to use webhooks, you must have the webhooks feature enabled for your team. If you need help enabling this feature, please contact your Account Executive or you can contact support. Once your team has access to this feature, click the "Enable" button.

Step 2: Configure a new webhook. Enter the URL of your system that will receive the webhook. Select the event type and choose which event actions you'd like to be notified of.

Note: Once you have saved a webhook, it will be disabled by default. We recommend testing your webhook before enabling.

Step 3: Test your webhook. Click the "Test" button to bring up the testing form. This will send a sample request to your webhook URL. Optionally, you can include a deal ID and specify an event type/action to receive an accurate representation of the payload.

Step 4: Enable your webhook. Once you have tested your webhook and have verified the connection to your system, use the toggle circled below.

Step 4: Manage your webhook. If you'd like to manage an existing webhook, click the "Edit" button. This will allow you to edit your webhook configuration, as well as delete your webhook.

Webhook example

Now that you've configured a webhook, we will cover what an incoming webhook request will look like.

Method: POST

Content-Type: application/body

Body:

{
    "eventType": "dealStatus",
    "eventAction": "create",
    "id": "839b430c5271478727cc6c1bcce0507d",
    "eventTime": 1681759293586,
        "meta": {
	    "dealID": "-NTFeZmcf5r5u7AAzRc_",
	    "name": "Demo Agreement",
	    "sourceTeam": "WebhookTestingTeam1d9c55fd17f5",
	    "sourceTemplate": "demo-agreement",
	    "status": "todo",
	    "updated": "1681759292601"
    },
    "webhookID": "-NTFeYXqSzWk09QGIuij"
}

Webhook payload object

Common Attributes

These attributes will be included in the payload JSON of every webhook.

Name	Type	Description
eventType	string	The type of event that occurred. (Deal Status)
eventAction	string	Further detail related to the event type.
eventTime	integer	The time that the event occurred, represented as a unix timestamp in milliseconds.
meta	object	An object containing more data that is specific to the event.
id	string	The ID of the event.
webhookID	string	The ID of webhook.

Event Specific Attributes

Depending on the event type, the "meta" attribute mentioned above can contain different data that is related to the event.

Deal Status Attributes

Name	Type	Description
dealID	string	The ID of the deal.
name	string	The name of the deal.
sourceTeam	string	The team that the deal belongs to.
sourceTemplate	string	The template used to generate the deal.
status	string	The current status of the deal.
updated	string	When the deal was updated, represented as a unix timestamp in milliseconds.

Webhook Retry Logic

After sending a webhook to your configured URL, if we do not receive a successful response (HTTP status code 200-299) we will attempt to retry that request up to 50 times. Below is the retry schedule:

Retry Number	Retry After X Minutes
2	1
3	2
4	4
5	8
6	16
7	32
8-50	60

Once we have made 50 attempts without success, we will automatically set the webhook to disabled.