Webhooks 2.0

In Webhooks 2.0 signNow API introduces entities to set up the scope of events available for callbacks. The two entities you can now use are document and user. To set up the scope, {entity_id} is required for every event subscription.

The event subscription

Attributes
  • data array[object]
    Contains event subscription attributes
  • id string
    Unique identifier of the event subscription
  • event string
    The type of the event. Learn more in Event types
  • entity_id string
    Unique identifier of the entity (user or document object) that sets the scope for the event.
  • action string
    Type of action required when the event is triggered. So far, the only available action is callback.
  • json_attributes object
    The callback attributes: callback_url, integration_id
  • created integer
    Unix timestamp for when the subscription was created.
Example event subscription in response here:
                { 
              
                  "data": [ 
              
                    { 
              
                      "id": "391a4c4a267b48c2a8e90ff802d4ae40fa051af6", 
              
                      "event": "user.document.create", 
              
                      "entity_id": 18972165, 
              
                      "action": "callback", 
              
                      "json_attributes": { 
              
                        "use_tls_12": true, 
              
                        "docid_queryparam": true, 
              
                        "integration_id": "b98fc00add6b43a606bc527c81eee741bf16a7d8", 
              
                        "callback_url": "http://callback-url.com", 
              
                        "headers": { 
              
                          "string_head": "test", 
              
                          "int_head": 12, 
              
                          "bool_head": false, 
              
                          "float_head": 12.24 
              
                        } 
              
                      }, 
              
                    "created": 1575381580 
              
                  } 
              
                ], 
              
                "meta": { 
              
                  "pagination": { 
              
                    "total": 1, 
              
                    "count": 1, 
              
                    "per_page": 15, 
              
                    "current_page": 1, 
              
                    "total_pages": 1, 
              
                    "links": [] 
              
                    } 
              
                  } 
              
                }
              

Create event subscription

Allows to subscribe an external service(callback_url) to a specific event of user or document. Authorization: Bearer or Basic.

Parameters
  • event required
    Name of the event
  • entity_id required
  • action required
  • callback required
  • use_tls_12 optional
  • docid_queryparam optional
  • string_head optional
  • int_head optional
  • bool_head optional
  • float_head optional
Returns

Returns "Id", "link", "Location" parameter in Headers of response. Returns an error when:

  • “attributes must not be empty” - “attributes” array is missing or empty
  • “‘callback’ is missing.” - required parameter “callback” is missing
  • “Action must be equal ‘callback’” - required parameter “action” is missing OR value of “action” parameter differs from ‘callback’
  • “event must not be empty” - required parameter “event” is missing or has an empty value
  • “event must be string” - value of the “event” parameter is not a string
  • “callback must be string” - value of the “callback” parameter is not a string
  • “callback must be url” - value of “callback” parameter is not an URL
  • “Invalid integration id - {integration_id}” - value of “integration_id” parameter doesn’t exist in database
POST /api/v2/events
                  
                    curl 
                    -X POST
                     \
                  
                
                  
                      https://api-eval.signnow.com/api/v2/events
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
                  
                      -H
                     'Content-Type: 
                     application/json'
                     \
                  
                
                  
                      -d
                     '{
                  
                
                  
                       "event": 
                     "document.fieldinvite.sent", 
                  
                
                  
                       "entity_id": 
                     "63fde884ad755149ff213563de654f9a61a1884c", 
                  
                
                  
                       "action": 
                     "callback", 
                  
                
                  
                       "attributes": 
                     {, 
                  
                
                  
                       "callback": 
                     "https://your.resource.com/", 
                  
                
                  
                       "use_tls_12": 
                     true, 
                  
                
                  
                       "integration_id": 
                     "b98fc00add6b43a606bc527c81eee741bf16a7d8", 
                  
                
                  
                       "docid_queryparam": 
                     true, 
                  
                
                  
                       "headers": 
                     {, 
                  
                
                  
                         "string_head": 
                     "test", 
                  
                
                  
                         "int_head": 
                     12, 
                  
                
                  
                         "bool_head": 
                     false, 
                  
                
                  
                         "float_head": 
                     12.24, 
                  
                
                  
                        }
                  
                
                  
                      }
                  
                
                  
                     }'
                  
                

There are "Id", "link", "Location" parameter in Headers of response.

Get event subscription

Gets information about all subscriptions to events made with a specific application.

Parameters (response)
  • id required
  • event required
  • entity_id required
  • action required
  • use_tls_12 required
  • docid_queryparam required
  • callback_url required
  • string_head required
  • int_head required
  • bool_head required
  • float_head required
  • created required
  • pagination required
Returns

Returns information about all subscriptions to events made with a specific application.

GET /api/v2/events
                  
                    curl 
                    -X GET
                     \
                  
                
                  
                      https://api-eval.signnow.com/api/v2/events
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Basic {{basic_authorization_token}}'
                  
                
Response
                    { 
                
                    "data": [ 
                
                      { 
                
                        "id": "391a4c4a267b48c2a8e90ff802d4ae40fa051af6", 
                
                        "event": "user.document.create", 
                
                        "entity_id": 18972165, 
                
                        "action": "callback", 
                
                        "json_attributes": { 
                
                          "use_tls_12": true, 
                
                          "docid_queryparam": true, 
                
                          "integration_id": "b98fc00add6b43a606bc527c81eee741bf16a7d8", 
                
                          "callback_url": "http://callback-url.com", 
                
                          "headers": { 
                
                            "string_head": "test", 
                
                            "int_head": 12, 
                
                            "bool_head": false, 
                
                            "float_head": 12.24 
                
                          } 
                
                        }, 
                
                      "created": 1575381580 
                
                    } 
                
                    ], 
                
                    "meta": { 
                
                    "pagination": { 
                
                      "total": 1, 
                
                      "count": 1, 
                
                      "per_page": 15, 
                
                      "current_page": 1, 
                
                      "total_pages": 1, 
                
                      "links": [] 
                
                      } 
                
                    } 
                
                  }
                

Delete event subscription

Unsubscribes an external service (callback_url) from specific events of user or document. Authorization: Bearer or Basic.

Authorization: Bearer - deletes event subscriptions created with Bearer token of the respective user;

Authorization: Basic - deletes any event subscription of the respective API app.

Parameters
  • event_subscription_id required
    ID of an event subscription to delete
Returns

Returns an error when:

  • For basic auth: Application id which is used for request differs from application id created given event subscription
  • For bearer auth: The event subscription was created by another user
  • Value of “uniqueEventId” doesn’t exist in database
DELETE /api/v2/events/{event_subscription_id}
                  
                    curl 
                    -X DELETE
                     \
                  
                
                  
                      https://api-eval.signnow.com/api/v2/events/{{event_subscription_id}}
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
Response
                  None 
                

Update event subscription

Allows changing an existing event subscription. Authorization: Bearer or Basic.

Authorization: Bearer - updates event subscriptions created with Bearer token of the respective user;

Authorization: Basic - updates any event subscription of the respective API app.

Parameters
  • event_subscription_id required
    ID of an event subscription to update
  • event required
  • entity_id required
  • action required
  • callback required
  • use_tls_12 required
  • integration_id required
  • docid_queryparam required
  • string_head required
  • int_head required
  • bool_head required
  • float_head required
Returns

Returns ID of the updated event subscription. Returns an error when:

  • “attributes must not be empty” - “attributes” array is missing or empty
  • “‘callback’ is missing.” - required parameter “callback” is missing
  • “Action must be equal ‘callback’” - required parameter “action” is missing OR value of “action” parameter differs from
  • ‘callback’
  • “event must not be empty” - required parameter “event” is missing or has an empty value
  • “event must be string” - value of the “event” parameter is not a string
  • “callback must be string” - value of the “callback” parameter is not a string
  • “callback must be url” - value of “callback” parameter is not an URL
  • “Invalid integration id - {integration_id}” - value of “integration_id” parameter doesn’t exist in database
PUT /api/v2/events/{event_subscription_id}
                  
                    curl 
                    -X PUT
                     \
                  
                
                  
                      https://api-eval.signnow.com/api/v2/events/{{event_subscription_id}}
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
                  
                      -H
                     'Content-Type: 
                     application/json'
                     \
                  
                
                  
                      -d
                     '{
                  
                
                  
                       "event":
                     "document.fieldinvite.sent"
                  
                
                  
                       "entity_id":
                     "63fde884ad755149ff213563de654f9a61a1884c"
                  
                
                  
                       "action":
                     "callback"
                  
                
                  
                       "attributes":
                     {
                  
                
                  
                        "callback":
                     "https://your.resource.com"
                  
                
                  
                        "use_tls_12":
                     true
                  
                
                  
                        "integration_id":
                     "b98fc00add6b43a606bc527c81eee741bf16a7d8"
                  
                
                  
                        "docid_queryparam":
                     true
                  
                
                  
                        "headers":
                     {
                  
                
                  
                         "string_head":
                     "test"
                  
                
                  
                         "int_head":
                     12
                  
                
                  
                         "bool_head":
                     false
                  
                
                  
                         "float_head":
                     "12.24 "
                  
                
                  
                      }
                  
                
                  
                     }
                  
                
                  
                    }'
                  
                
Response
                  {
                
                    "id": "391a4c4a267b48c2a8e90ff802d4ae40fa051af6"
                
                  }