Flow Webhooks

Subscribe to Webhook events for data submitted through flows

Description

Webhooks provide a simple method for obtaining automated data from Attestr servers without having to directly access the APIs to retrieve the data that end users provide utilising flows. For information related to webhook configuration, please refer to Webhooks. Flows support following three types of events.

flowx.completed
flowx.skipped
flowx.errored

To enable webhooks, the API input parameter webhook must be set as true while initiating the Create Handshake API

Event Definition

All webhook events provided by Attestr, follow a standard structure as defined below.

Key	Type	Description	Min Version	Max Version
event	String	Name of the event	v1
payload	Object	Event specific payload object	v1

Sample event payload

JSON
    
 
{  "event": "flowx.completed",  "payload": {    .....    .....    .....  }}
Copy

Flowx.completed Event

This event is triggered on successful completion of the flow on the end user's device.

Flowx.completed Event Payload

Key	Type	Description	Min Version
_id	String	Handshake Id, same as generated in the Create Handshake API	v1
tag	String	Unique tag number provided by the customer while initiating a new handshake in Create Handshake API	v1
number	String	Unique handshake human readable number as generated by the Attestr backend.	v1
requestId	String	Unique tracking ID used for Attestr internal purposes and debugging issues.	v1
result	Object	Result object as explained in Execution Result API	v1
resultSignature	String	Result signature which can be used to establish the authenticity of the result. Refer to Execution Result API for details.	v1
flowId	String	Flow Id as mapped to this handshake, same as provided as input in the Create Handshake API	v1
snapshot	String	Flow version if provided in the Create Handshake API else null.	v1
updated	Number	Unix timestamp in milliseconds of the last updated time	v1

Sample flowx.completed event payload

JSON
    
 
{  "event": "flowx.completed",  "payload": {    "_id": "DS0ZiN5T74YVMAKIbm",    "tag": "USERID-1231",    "number": "3897-519843-9268",    "requestId": "febbe10a-8a1a-4001-905f-9370653f6ab0",    "consumed": true,    "result": {      "FS0aZTfJRHZVX8hG7a": {        "output": {          "valid": true,          "name": "GITANJALI RAHEJA",          "ifsc": null,          "status": "ACTIVE"        },        "input": {          "acc": "501000123456778",          "ifsc": "HDFC0000314",          "tag": "USERID-1231"        }      }    },    "resultSignature": "e19b244e3499166e4b93d51570a243b9bc338727ed6db5873122b2fe3e46d50c",    "flowId": "FX0fVbORD6o0lmrtkM",    "snapshot": "b5ec4950-dc98-4e47-90c2-dd10e17929ab",    "updated": 1675397411000  }}
Copy

Flowx.skipped Event

This event is triggered if the end user terminates the flow execution by clicking the cancel button.

Flowx.skipped Event Payload

Key	Type	Description	Min Version
_id	String	Handshake Id, same as generated in the Create Handshake API	v1
tag	String	Unique tag number provided by the customer while initiating a new handshake in Create Handshake API	v1
number	String	Unique handshake human readable number as generated by the Attestr backend.	v1
requestId	String	Unique tracking ID used for Attestr internal purposes and debugging issues.	v1
flowId	String	Flow Id as mapped to this handshake, same as provided as input in the Create Handshake API	v1
snapshot	String	Flow version if provided in the Create Handshake API else null.	v1
udpated	Number	Unix timestamp in milliseconds of the last updated time	v1

Sample flowx.skipped event payload

JSON
    
 
{  "event": "flowx.skipped",  "payload": {    "_id": "DS0ZiN5T74YVMAKIbm",    "tag": "USERID-1231",    "number": "3897-519843-9268",    "requestId": "febbe10a-8a1a-4001-905f-9370653f6ab0",    "consumed": true,    "flowId": "FX0fVbORD6o0lmrtkM",    "snapshot": "b5ec4950-dc98-4e47-90c2-dd10e17929ab",    "updated": 1675397411000  }}
Copy

Flowx.errored Event

This event is triggered when the flow is terminated due to any errors encountered during the flow execution. Errors can be either related to data, low balance, configuration problems or other general server errors.

Flowx.errored Event Payload

Key	Type	Description	Min Version
_id	String	Handshake Id, same as generated in the Create Handshake API	v1
tag	String	Unique tag number provided by the customer while initiating a new handshake in Create Handshake API	v1
number	String	Unique handshake human readable number as generated by the Attestr backend.	v1
requestId	String	Unique tracking ID used for Attestr internal purposes and debugging issues.	v1
flowId	String	Flow Id as mapped to this handshake, same as provided as input in the Create Handshake API	v1
snapshot	String	Flow version if provided in the Create Handshake API else null.	v1
error	Object	Error object. See below for definition	v1
udpated	Number	Unix timestamp in milliseconds of the last updated time	v1

Error Object Definition

Key	Type	Description	Min Version
code	String	Unique error code assigned by Attestr	v1
httpStatusCode	String	Standard Http status code for this error type	v1
message	String	Error message.	v1
stage	String	Stage Id in the flow which encountered this error.	v1
original	Object	Error object if the error is caused due to an underlying problem with the customer's account or due to data error failures after retry attempts limit is exceeded.	v1

Sample flowx.errored event payload

JSON
    
 
// Sample error for low wallet balance{  "event": "flowx.errored",  "payload": {    "_id": "DS0ZiN5T74YVMAKIbm",    "tag": "USERID-1231",    "number": "3897-519843-9268",    "requestId": "febbe10a-8a1a-4001-905f-9370653f6ab0",    "consumed": true,    "flowId": "FX0fVbORD6o0lmrtkM",    "snapshot": "b5ec4950-dc98-4e47-90c2-dd10e17929ab",    "error": {      "code": 5001,      "httpStatusCode": 500,      "message": "Request could not be completed. Please try later.",      "retry": false,      "stage": "FS0aZTfJRHZVX8hG7a",      "original": {        "httpStatusCode": 400,        "code": 4005,        "message": "Operation could not be performed due to low credits balance",        "appError": true      }    }  },  "updated": 1675397411000}
Copy

JSON
    
// Sample error for retry attempts exceeded{  "event": "flowx.errored",  "payload": {    "_id": "DS0evVS1aKhzW-G1n5",    "tag": "USERID-1231",    "number": "3897-511360-0858",    "requestId": "347715dc-dce4-4e05-a54f-5387d8471a3c",    "consumed": true,    "flowId": "FX0fVbORD6o0lmrtkM",    "snapshot": "a9a2b900-6e03-45ce-a3be-7200637d7305",    "error": {      "httpStatusCode": 400,      "retry": true,      "code": 40012,      "message": "The account number is either not valid or in blocked / closed state. Please provide a different account number.",      "stage": "FS0aZTfJRHZVX8hG7a"    },    "updated": 1675397411000  }}
Copy

Retry and Timeout

As explained on Webhooks page, webhook events from Attestr are only triggered once and have a 5-second timeout. Within 5 seconds, the registered webhook URL must return a 200 success response. It's possible that events are sent out of order. If your system does not respond to the event within 5 seconds, you can still use the Execution Result API to receive the handshake data.

Last updated on