Versions Compared

Version Old Version 17 New Version Current
Changes made by

Volodymyr Machula

Volodymyr Machula

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

Depending on whether one wants to use the default payload or a GraphQL-constructed payload for webhooks, there might be two different types of views for the structure. For constructing the webhook payload, please use values defined in https://gql.doo.net. For details on how to do that, use the steps defined in Constructing GraphQL body.

Webhook Configuration for Default Payload

...

Configuration object

{ "name": "<name>", "description": "<description>", "hooks": [
Code Block
languagejs
json
{
      "typename": "event<webhook_configuration_createdname>",

     "methoddescription": "POST<webhook_configuration_description>",
 
    "endpointevent_id": "<hook<event_endpoint>"
    },
    {
 id>",
    "type": "event_removed",
      "method"guide_id": "POST<event_guide_id>",
      "endpointhooks": "<hook_endpoint>"
[
   },     {
      "type": "event_updated",       "methodtype": "POST",
      "endpoint": "<hook_endpoint>"
    }<webhook_type>",
    {       "type": "order_created",       "method": "POST",
      "endpoint": "<hook_endpoint>"
 
  },     {       "typeendpoint": "order<external_endpoint_removedurl>",
      "method": "POST",       "endpointorigin": "<hook_endpoint>"
    },
{
   {       "type": "order_updated",       "method": "POST",
 
    "endpoint": "<hook_endpoint>"     },     {       "type"endpoint": "order_cancelled",
      "method": "POSThttps://gql.doo.net",
      "endpoint": "<hook_endpoint>"     }   ],   "authenticationbody": {
    "grant<graphql_typequery>":
"client_credentials",     "endpoint": "<oauth_endpoint>",     "credentials": {
		"client_id": "<client_id>",}
       	"client_secret": "<client_secret>" 	},
    "header_format": "Authorization"],
    "header_value_formatauthentication": "Bearer %ACCESS_TOKEN%"
  }
}

Webhook Configuration for GraphQL-based Payload

Example how to provide GraphQL setting. In API request, body must be escaped
Code Block
languagejs
{
  "name": "<name>",   "description": "<description>",
  "hooks": [
    {
      " "grant_type": "eventclient_createdcredentials",
      "method": "POST",       "originendpoint":{
          "method":"POST",
          "endpoint":"https://<some "<external_oauth_endpoint_url>",
          "bodycredentials":" {<this
is body as enclosed JSON string>}"       },
      "endpoint"client_id": "<hook_endpoint>doo",
    }   ],   "authentication": {
    "grantclient_typesecret": "<external_client_credentialssecret>",
    "endpoint": "<oauth_endpoint>",   },
 "credentials": { 		"client_id": "<client_id>", 
    	"clientheader_secretformat": "<client_secret>"
	}Authorization",
    "header_format": "Authorization",     "header_value_format": "Bearer %ACCESS_TOKEN%"
    }
}
Info

NOTE: In case you don't have OAuth endpoint and want to omit the authorization step with your server - don't include authentication property into the AddWebhook object

Parameters

If the <external_endpoint_url> is not protected with OAuth, you can omit the authentication object in the configuration object. In this case, doo will send the webhook request without access_token. See Webhook requests from doo to the external system for more information.
Parameters
In the configuration object, you can see a lot more configurations than described in the table below. We do not recommend changing any parameters that are not listed in the table below.
Parameter
Required
Description
<name>
<webhook_configuration_name>
Yes
Webhook configuration name.
<description>
<webhook_configuration_description>
No
Webhook configuration 
 detailed 
 description.
<hook
<event_
endpoint>
Yes
Your server URL where you want to receive the webhook
Can be separate for each hook type
<oauth_endpoint>
Yes
Your server OAuth endpoint URL
<client_id>
No
Client Id for your OAuth endpoint 
<client_secret>
No
Client Secret for your OAuth endpoint 
Examples
Default case:
JSON Default case
 Code Block
languagejs
{
  "name": "My Test Webhook",
  "description": "Webhook for testing all the hook types",
  "hooks": [
    {
      "type": "event_created",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "event_removed",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "event_updated",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "order_created",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "order_removed",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "order_updated",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    },
    {
      "type": "order_cancelled",
      "method": "POST",
      "endpoint": "https://requestb.in/123"
    }
  ],
  "authentication": {
    "grant_type": "client_credentials",
    "endpoint": "https://requestb.in/123",
    "credentials": {
    	"client_id":"doo", 
    	"client_secret":"super-strong-secret"
    },
    "header_format": "Authorization",
    "header_value_format": "Bearer %ACCESS_TOKEN%"
  }
}
GraphQL case:
JSON GraphQL example with concrete values
...
id>
No
doo Event ID. 
If specified, the webhook configuration will be attached only to the specified event. 
If neither <event_id> nor <event_guide_id> is specified, the webhook configuration will be attached to the whole organization.
<event_guide_id>
No
doo Event Guide ID.
If specified, the webhook configuration will be attached to all the events created with the specified event guide.
If neither <event_id> nor <event_guide_id> is specified, the webhook configuration will be attached to the whole organization.
<webhook_type>
Yes
Webhook type name from Supported resources and webhook types without on_ preffix.
<external_endpoint_url>
Yes
External API endpoint where doo sends the webhook payload for the specified webhook type.
See Webhook requests from doo to the external system 
<graphql_query>
Yes
GraphQL query which specifies the webhook payload structure.
See How to prepare GraphQL query for webhook configuration? 
<external_oauth_endpoint_url>
Yes, if authentication object does exist in the configuration object
External authorization OAuth API endpoint where doo can retrieve the access_token.
See Webhook requests from doo to the external system 
<external_client_secret>
Yes, if authentication object does exist in the configuration object
A valid OAuth Client Secret which doo will use to retrieve theaccess_token.
Example
 Code Block
languagejson
{
    "name":"Sample-Org",     "description":"Sample-Description",
    "hooks":[
        {
            "type":"event_created""Test webhook",
            "method":"POST",
            "origin":{
                "method":"POST",
   "description": "Event creation and updates webhook subscription",
            "endpoint":"https://gql.doo.net",
                "body":"{\"operationName\":\"EventShort\",\"variables\":{\"id\":\"%EVENT_ID%\"},\"query\":\"query EventShort($id: ID!) {\\n event(id: $id) {\\n title\\n }\\n}\\n\"}"
"hooks": [
        {
             },
            "endpoint":"http://requestbin.net/r/123"
        },
        {
            "type":"event_removed"type": "event_created",
            "method":"POST",
            "origin":{
                "method":"POST",
 
              "endpoint": "https://gqlcompany.doo.netcom/receive-doo-webhooks",
   
            "body":"{\"operationName\":\"EventShort\",\"variables\":{\"id\":\"%EVENT_ID%\"},\"query\":\"query EventShort($id: ID!) {\\n event(id: $id) {\\n title\\n }\\n}\\n\"}"
            },
            "endpoint":"http://requestbin.net/r/123"
        },
        origin": {
            "type":"event_updated",             "method":"POST",
            "origin":{
                "method":"POST",
                "endpoint": "https://gql.doo.net",
                "body": "{\"operationName\":\"EventShort\"null,\"variables\":{\"ideventId\":\"%EVENT_ID%\"},\"query\":\"query EventShort($id$eventId: ID!) {\\n event(id: $id$eventId) {\\n id title\\n }\\n}\\n\"}"
            },
   
        "endpoint":"http://requestbin.net/r/123"
        },
        {
            "type": "orderevent_cancelledupdated",
            "method":"POST",
            "origin":{
                "method":"POST",
                "endpoint": "https://gqlcompany.doo.netcom/receive-doo-webhooks",
                "body":"{\"operationName\":\"OrderShort\",\"variables\":{\"id\":\"%ORDER_ID%\"},\"query\":\"query OrderShort($id: ID!) {\\n  order(id: $id) {\\n    hash\\n  }\\n}\\n\"}""origin": {
            },             "endpoint":"http://requestbin.net/r/123"
        },
        {
            "type":"order_created",
            "method":"POST",             "origin":{
                "method":"POST",
                "endpoint": "https://gql.doo.net",
                "body":"{\"operationName\":\"OrderShort\",\"variables\":{\"id\":\"%ORDER_ID%\"},\"query\":\"query OrderShort($id: ID!) {\\n  order(id: $id) {\\n    hash\\n  }\\n}\\n\"}"
            },
            "endpoint":"http://requestbin.net/r/123"
        },
        {
            "type":"order_removed",
            "method":"POST",
            "origin":{
                "method":"POST",
                "endpoint":"https://gql.doo.net",
                "body":"{\"operationName\":\"OrderShort\"null,\"variables\":{\"ideventId\":\"%ORDER%EVENT_ID%\"},\"query\":\"query OrderShort($id$eventId: ID!) {\\n  order(id: $id) {\\n    hash\\n  }\\n}\\n\"}"
            },
            "endpoint":"http://requestbin.net/r/123"
        },
        {
            "type":"order_updated",
            "method":"POST",
            "origin":{
                "method":"POST",
                "endpoint":"https://gql.doo.net",
                "body":"{\"operationName\":\"OrderShort\",\"variables\":{\"id\":\"%ORDER_ID%\"},\"query\":\"query OrderShort($id: ID!) {\\n  order(id: $id) {\\n    hash\\n  }\\n}\\n\event(id: $eventId) { id title }}\"}"
            },
            "endpoint":"http://requestbin.net/r/123"
        }
    ],
    "authentication": {
        "grant_type": "client_credentials",
        "endpoint": "httphttps://requestbincompany.net/r/456com/authorize-doo-webhooks",
        "credentials": {
            "client_id": "doo",
            "client_secret": "super-strong-secret"
        },
        "header_format": "Authorization",
        "header_value_format": "Bearer %ACCESS_TOKEN%"
    }
}


Constructing GraphQL body
Below, we will demonstrate a simple case of constructing the trigger payload using GraphQL:
...
Go to https://gql.doo.net
Under the section HTTP Headers, put the Api_Key and Access Token in this format:
 Code Block
{
  "x-api-key":"<api_key>",
 "Authorization":"Bearer <access_token>"
}
Provide Query Variables. Example:
 Code Block
{"id": <event_id>}
...
Provide the body. Example:
 Code Block
query EventShort($id: ID!){
  event(id: $id) {
    title,
    startDate,
    endDate
  }
}
to construct a body, one can use the Schema (green button on the right). There you pick the desired entities and then use the detailed variables to construct the payload.
...
Verify the payload. To do that, simply click on the Play button and you will get a complete payload in json and potentially discover mistakes in your body query.
...