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
Headers
Example
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
Parameters
Request
Response
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.
Parameters
Request
Response
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.
Parameters
Request
Response
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.
Parameters
Request
Response
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
Parameters
Request
Response
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
Request
Response
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
Parameters
Request
Response
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
}

Strong Customer Authentication

Next - Machine Learning

Intro to ML

Last updated -1

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`.

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.

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.`

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

Path Parameters	Type	Description
`<webhook_id>`	`string`	ID of the Webhook to receive.