Webhooks

Webhooks allow you to keep track of your data without having to constantly poll our APIs for updates.

Webhook Object

You can Create and Delete webhooks through our Dashboard. We are working to expand this feature, so stay tuned for updates. ‌

Attribute

Type

Description

event_type

string

The type of Event. Can be from any of the event type list (see below).

endpoint

string

The URL to call when the Webhook is triggered.

secret

string

A SHA-256 secret used to secure the Webhook communication.

active

boolean

Sets if related Event is dispatched. Default is true.

deleted

boolean

Whether the Webhook is deleted. Default is false.

verified

boolean

Whether the Webhook endpoint is verified. Default is false.

Receive Webhook

Changes since API version 2019-02-01

2019-08-15 - Headers renamed

We are deprecating the old headers, which means it is not a breaking change but it's recommended to update them as soon as possible.

X-Share-Webhook-Signature becomes X-BuiltOn-Webhook-Signature
X-Share-Webhook-Type becomes X-BuiltOn-Webhook-Type

Key	Description

X-BuiltOn-Webhook-Signature

Verifies that the incoming requests are legitimate, you should hash the response body with the SHA-256 secret and verify that it matches the X-BuiltOn-Webhook-Signature header you receive in the request.

X-BuiltOn-Webhook-Type

Two types that describe the nature of the webhook:

WebhookConfirmation This type of message is sent when we are verifying your endpoint.
WebhookMessage
This type of message is sent when we send a webhook to your endpoint.

X-BuiltOn-Webhook-Retries

How many times BuiltOn tried to send a webhook to your endpoint.

BuiltOn will try to send 5 times. After the limit is reached, the retrying process will stop.

HTTP/1.1 200 OK
Content-Type: application/json
X-BuiltOn-webhook-Type: WebhookMessage
X-BuiltOn-webhook-Signature: 02d522b33c34e0655e8a97c49b5d038a2abd93cb86f4608b9e7febe0e28acf64
X-BuiltOn-Event-Retries: 0

{
   "object_type":"machine_learning_model",
   "previous_data":{
      "training_status":"CREATED"
   },
   "kind":"machine_learning_model.runnable",
   "object":{
      "evaluation":{},
      "human_id":"XL3R47",
      "deleted":false,
      "training_status":"RUNNABLE",
      "created":1565770053099,
      "modified":1565770059308,
      "company":"5ce68495873a43000d3a0d1c",
      "_id":"5d53c1451a7e86000fd0d852"
   },
   "url":"https://enf38z1loomb1zg.m.pipedream.net/"
}

Create a Webhook through the Dashboard

Go to the Webhooks and click New webhook +.
FIll in the event_type and the endpoint.
Go use your new webhook.

Attribute

Type

Description

event_type

string

The type of Event.

endpoint

string

The URL to call when the webhook is triggered.

Delete a Webhook through the Dashboard

Go to Webhooks and click the webhook you want to delete. You should see 'Delete webhook' below its details.
Click the X and confirm you want to delete it.
Mourn your deleted webhook.

Event Types

Event Type

Description

order.created

Order created

order.updated

Order updated

order.cancelled

Order cancelled

user.created

User created

user.updated

User updated

user.deleted

User deleted

subscription.created

Subscription created

subscription.updated

Subscription updated

subscription.deleted

Subscription deleted

subscription.activated

Subscription activated

subscription.future

Subscription postponed

subscription.completed

Subscription completed

subscription.non_renewing

Subscription stopping the next cycle

subscription.cancelled

Subscription cancelled

payment.created

Payment created

payment.updated

Payment updated

payment.deleted

Payment deleted

payment.succeeded

Payment succeeded

payment.processing

Payment processing

payment.failed

Payment failed

payment.captured

Payment captured

payment.cancelled

Payment cancelled

payment.pending

Payment pending

payment.requires_auth

Payment requires an authentication action

product.created

Product created

product.updated

Product updated

product.deleted

Product deleted

plan.created

Plan created

plan.updated

Plan updated

plan.deleted

Plan deleted

machine_learning_model.created

ML model created

machine_learning_model.runnable

ML model training is ready to start

machine_learning_model.starting

ML model is starting the training process

machine_learning_model.training

ML model has started and is currently being training

machine_learning_model.failed

ML model has failed to train

machine_learning_model.succeeded

ML model succeeded the training process

machine_learning_model.insufficient_data

ML model couldn't start the training process, because there is no sufficient data

machine_learning_model.evaluation_ready

ML model evaluation is available

‌Admin Role

Create a Webhook

Body Parameters

Type

Description

event_type

string

The type of event to receive information about.

endpoint

string

The URL to call when the Webhook is triggered.

active

boolean

Sets if related Event is dispatched. Default is true.

POST /webhooks HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
    "endpoint": "http://requestbin.fullcontact.com/asdfasdf",
    "event_type": "order.created"
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "created": {"$date": 1499767018360},
    "updated": {"$date": 1499767018360},
    "event_type": "order.created",
    "deleted": false,
    "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
    "endpoint": "http://requestbin.fullcontact.com/1o2mfpb1",
    "verified": false,
    "active": true
}

Verify a Webhook

The Webhook has to be verified before related data on related Events are dispatched. The API tries to verify the endpoint when the Webhook is created. If the endpoint returns an HTTP status code 2XX then the Webhook is set to verified.

If an endpoint is updated, then the Webhook is not verified anymore. It is possible to manually try to verify the endpoint by doing the following request.

Body Parameters

Type

Description

<webhook_id>

string

ID of the webhook to be verified.

POST /webhooks/5964a0ead57ba2036750a3b4/verify HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "created": {"$date": 1499767018360},
    "updated": {"$date": 1499767018360},
    "event_type": "order.created",
    "deleted": true,
    "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
    "endpoint": "https://www.google.com",
    "verified": true,
    "active": true
}

Simulate a Webhook

It is possible to simulate the response from a Webhook to check the format of the data. The API will trigger a fake event related to the Webhook type and send the data to the specified endpoint.

Body Parameters

Type

Description

<webhook_id>

string

ID of the webhook to be simulated.

POST /webhooks/<webhook_id>/simulate HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 204 OK
Content-Type: application/json

{}

Update a Webhook

Note that if the endpoint is updated, then you will need to verify the webhook before related Events are dispatched.

Body Parameters

Type

Description

event_type

string

The type of event to receive information about.

endpoint

string

The URL to call when the Webhook is triggered.

PUT /webhooks/5964a0ead57ba2036750a3b4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

{
    "endpoint": "https://www.google.com"
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "created": {"$date": 1499767018360},
    "updated": {"$date": 1499767018360},
    "event_type": "order.created",
    "deleted": false,
    "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
    "endpoint": "https://www.google.com",
    "verified": false,
    "active": true
}

Receive Webhook by ID

Path Parameters

Type

Description

<webhook_id>

string

ID of the Webhook to receive.

GET /webhooks/5964a0ead57ba2036750a3b4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "created": {"$date": 1499767018360},
    "updated": {"$date": 1499767018360},
    "event_type": "order.created",
    "deleted": false,
    "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
    "endpoint": "https://www.google.com",    
    "verified": true,
    "active": true
}

Get All Webhooks

GET /webhooks HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
        "company": {"$oid": "57ee9c71d76d431f8511142f"},
        "created": {"$date": 1499767018360},
        "updated": {"$date": 1499767018360},
        "event_type": "order.created",
        "deleted": false,
        "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
        "endpoint": "https://www.google.com",
        "verified": true,
        "active": true
    }
]

Delete a Webhook

Path Parameters

Type

Description

<webhook_id>

string

The ID of the Webhook to delete. Attribute deletedwill be set to true.

DELETE /webhooks/5964a0ead57ba2036750a3b4 HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_id": {"$oid": "5964a0ead57ba2036750a3b4"},
    "company": {"$oid": "57ee9c71d76d431f8511142f"},
    "created": {"$date": 1499767018360},
    "updated": {"$date": 1499767018360},
    "event_type": "order.created",
    "deleted": true,
    "secret": "ed06e2f4e7bdb5ee6050695aba5ed3f2725fd3394df22f3a8a0c2856123a",
    "endpoint": "https://www.google.com",
    "verified": true,
    "active": true
}

PreviousRefunding NextIntro to ML

Last updated 4 years ago