Webhooks can be used to notify your system any time a record is created, updated, deleted, or a dispatch status is changed.

Add a webhook

Adding a webhook takes two steps:

Add a webhook connection
1. Open Manage > Integrations > Connections.
2. Select Add on the action menu.
3. Set Type to Webhook and fill out the URLs to notify when records are added, edited, deleted, or their status changes. Select Include form data if you wish to include the contents of the form submission in each webhook notification. You can also specify up to four HTTP headers to send with every request.
4. Click Add.
Assign the connection to a web service
1. Open Manage > Integrations > Web services.
2. Select Set Target on the action menu of an existing web service.
3. Select your connection in the Connection field. You can also specify which record events should trigger a webhook notification.
4. Click Add.

Multiple web services can use the same webhook connection as their target.

Request to your system

Any time records are added, edited, deleted, or their dispatch status is changed using the form and project of a web service with a web hook target, the following POST request will be sent:

Body

Notes

{
  "key": "abc123",
  "customerKey": "cde123",
  "submissionKey": "def456",
  "webserviceId": 
    "acme$$1234$$Published$$5678",
  "event": "create",
  "status": "new",
  "createTime": 
    "2019-08-20T16:55:20.130Z",
  "submission": {
    "key": "abc123",
    "id": "acme$$12345$$Published&&1",
    ...
  }
}

key is the key of the web hook notification. The same key value will be sent in any retries.
customerKey is the key of your customer account.
dispatchKey (not shown) is the key of the dispatch record. Included if a dispatch triggered the notification, or if a dispatch was used to create a new submission.
submissionKey is the key of the submission record. Included if a submission triggered the notification.
webserviceId is the identifier of the web service. Use this to identify the Project and Form that generated the webhook notification.
event is one of "create", "update", "delete", "status":
- create - The record was added.
- update - The record was changed.
- delete - The record was removed.
- status - The status of the dispatch record changed.
status is "new" for the first request and "retry" for any retries.
dispatchStatus (not shown) is the new status of a dispatch record.
createTime is the UTC date/time when the notification was created.
submission is the content of the form submission. Included only if Include form data is selected in the Connection. Uses the same format as a submission retrieved at /submissions/{key or id}

Response from your system

Your system should respond to the webhook request in one of the following ways:

Code	Body	Notes
2xx	{ "status": "failed", "message": "Error for the user" }	status can be one of "received", "completed", "failed". message (optional) is any message for the end user. Maximum 1,000 characters. The request will not be retried.
2xx	Empty	The status will be recorded as "received". The request will not be retried.
5xx	Ignored	The status will be recorded as "retry". The request will be retried up to 3 additional times at approximately 2, 4 and 8 minutes after the initial request. Read and connection timeouts are 3 seconds. A slower response will result in a retry. If all retries fail, the status will be recorded as "rejected".
Other	Ignored	The status will be recorded as "rejected". The request will not be retried.

Usage

Immediate response

If it is possible to process the record in under 3 seconds, respond with 200 OK and the final status of the process ("completed" or "failed") in the response body.

Delayed response

If more than 3 seconds is required to process the record, respond with 200 OK and an empty body to the initial request. The status of the webhook notification will be set to "received".

If you wish to update the webhook notification with the final status of the record in your system, send a PUT request using the key value from the original notification request to:

https://api.mydoforms.com/api/v2/notifications/{key}

Body	Notes
{ "status":"completed", "message":"One record updated." }	status can be one of "completed", "failed". message (optional) is any message for the end user. Maximum 1,000 characters.

This request must be authenticated by including an Authorization header that combines the webservice Id and the webservice password: Bearer {webservice Id}:{webservice password}

Response	Notes
{ "key": "abc123", "submissionKey": "def456", "webServiceId": "acme$$1234$$Published$$5678", "event": "create", "status": "completed", "message": "One record updated." }	Returns the updated notification.