Webhook Custom Template Overview

Service Type

A service refers to a third-party application service, typically based on an HTTP server. Currently, WorkZappy primarily supports the following service types: WorkZappy service, which is suitable for personalized customization and development by users.

Event Type

An event refers to information generated by the system itself or user operations that trigger events. Events include relevant business data and basic event information. Currently, WorkZappy supports the following events:

• Work

  • Create Work

  • Update Work

  • Delete Work

• Comment

  • Add Comment

  • Update Comment

  • Delete Comment

• Attachment

  • Upload Attachment

  • Delete Attachment

• Subtask

  • Add Subtask

  • Update Subtask

  • Delete Subtask

• Linked Work

  • Add Linked Work

  • Delete Linked Work

• Phase

  • Create Phase

  • Start / Restart Phase

  • Complete Phase

  • Delete Phase

The data content of events varies depending on the type of event. Please refer to the following data structure: Webhook Custom Template Variables

WorkZappy Custom JSON Template:

Currently, the system does not support custom template configuration options in WorkZappy format. All messages will be sent using the following template:

{
    "type": 
${event.type.id},
    "date": $
{trigger.date},
    "tenant": 
${tenant},
    "trigger": $
{trigger},
    "data": {
        "issue": 
${issue},
        "comment": $
{comment},
        "attachment": 
${attachment},
        "subtask": $
{subtask},
        "relationIssue":${relationIssue}
        "sprint": ${sprint}
    }
}

Request data example:

{
    "date": 1676627206432,
    "data": {
        "issue": {
            "summary": "Webhook Customized WorkZappy Service Messages",
            "dueDate": 1676628000000,
            "description": "The primary service we currently offer is called WorkZappy Service.",
            "project": {
                "name": "Sample Project",
                "description": "Click here to explore a sample project and discover the key features of WorkZappy!",
                "id": 900
            },
            "updateTime": 1676627206432,
            "priority": {
                "optionKey": "Medium",
                "name": "Medium",
                "id": 1200
            },
            "type": {
                "code": "story",
                "name": "story",
                "id": 1100
            },
            "url": "https://ligai.cn/app/work",
            "number": 8,
            "createBy": {
                "phone": "12345678901",
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },
             "follows": [
                {
                  "id": 101,
                  "name": "Bob",
                  "phone": "",
                  "email": "[e-mail]"
                 },
                 { "id": 102,
                   "name": "Alex",
                   "phone": "",
                   "email": "[e-mail]"
                  }
             ],
            "estimatePoint": {
                "autoCalculateFlag": 0,
                "value": 8
            },
            "createTime": 1676627206432,
            "updateBy": {
                "phone": "12345678901",
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },

            "id": 100,
            "startDate": 1676595600000,
            "status": {
                "code": "story-todo",
                "name": "No-started",
                "id": 4,
                "category": {
                    "name": "Todo",
                    "id": 4
                }
            }
        }
    },
    "trigger": {
        "date": 1676627206432,
        "user": {
            "phone": "12345678901",
            "name": "Bob",
            "id": 101,
            "email": "[e-mail]"
        }
    },
    "type": "Issue.Create",
    "tenant": {
        "id": 1
    }
}

WorkZappy Service Description

• Request Method: POST

• Request Header

Header	Description
X-WorkZappy-Event	Event identifier. The format is "object.action"	-
	Object	Description
	Issue	Work
	Comment	Comment
	Attachment	Attachment
	Subtask	Subtask
	RelationIssue	Linked Work
	LIA	Automation
	Webhook	Webhook
	Action	Description
	Create	Create
	Update	Update
	Start	Start: Often paired with the object Sprint to signify the initiation or resumption of an sprint.
	Complete	Complete: Commonly utilized with the object Sprint to denote the end or completion of an sprint.
	Delete	Delete
	Action	Operation. Usually used together with the object Automation, indicating automation operation.
	Test	Test. Typically used with object Webhooks to indicate a test operation of the webhook.
X-WorkZappy-WebHook-ID	Unique identifier for the configured webhook	-
X-WorkZappy-Type	Format of the request	-
	Format	Description
	WorkZappy	WorkZappy Service
X-WorkZappy-Ts	Timestamp of the request (in seconds)	-
X-WorkZappy-ID	Unique identifier for the request to identify a specific occurrence	-
X-WorkZappy-Retry-Num	Retry number. Initially set as 0 and incremented for each subsequent request	-
X-WorkZappy-Token	Token for the webhook configuration	-
X-WorkZappy-Sign	Data signature string (currently not supported)	-

• Request body data format: application/json; charset=utf-8. Default data format example:

{
    "date": 1675329348640,
    "data": {
        "issue": {
            "owner": {
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },
            "summary": "Webhook Custom WorkZappy Service Message",
            "dueDate": 1675332000000,
            "sprint": {
                "name": "Name of the Sprint",
                "id": 1400
            },
            "description": "The primary service we currently offer is called WorkZappy Service.",
            "project": {
                "name": "Sample Project",
                "description": "Click here to explore a sample project and discover the key features of WorkZappy!",
                "id": 900
            },
            "updateTime": 1675329348640,
            "priority": {
                "optionKey": "Highest",
                "name": "Highest",
                "id": 1200
            },
            "type": {
                "code": "story",
                "name": "Story",
                "id": 1100
            },
            "url": "https://ligai.cn/app/work",
            "number": 21,
            "createBy": {
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },
            "estimatePoint": {
                "autoCalculateFlag": 0,
                "value": 13
            },
            "createTime": 1675325728466,
            "updateBy": {
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },
            "assignee": {
                "name": "Bob",
                "id": 101,
                "email": "[e-mail]"
            },
            "follows": [{
                            "id": 101,
                            "name": "Bob",
                            "phone": "",
                            "email": "[e-mail]"
                    },
                    {
                            "id": 102,
                            "name": "Alex",
                            "phone": "", 
                            "email": "[e-mail]"
                    }
            ],
            "id": 100,
            "startDate": 1675213200000,
            "status": {
                "code": "scrum-development",
                "name": "Developer",
                "id": 4,
                "category": {
                    "name": "In Progress",
                    "id": 3
                }
            }
        }
        ,"relationIssue": {
                "destineIssues": [
                                {
                                        "destinationProjectId": 225724408,
                                        "destinationIssueId": 276042168,
                                        "relationshipType": "CAUSES"
                                }
                        ],
                        "fromIssue": {
                                "actionType": "delete",
                                "fromIssueId": 276135673
                        }
        },
        "sprint":{
            "goal": "Example Sprint Goals",
            "assigneeName": "Bob",
            "endDate": 1712592000000,
            "name": "[Example] Name of the Sprint",
            "closed": 1,
            "started": 1,
            "assignee": 101,
            "id": 1400,
            "projectId": "900",
            "startDate": 1711382400000,
            "completeDate": 1711422314378,
            "status": 4
        }
    },
    "customFields": [
                {
                        "customFieldName": "Cause of defect",
                        "fieldCode": "customfield_50776203",
                        "fieldValue": [
                                {
                                        "name": "Code error",
                                        "value": 50776207
                                }
                        ]
                }
        ],
    
    "trigger": {
        "date": 1675329348640,
        "user": {
            "name": "Bob",
            "id": 101,
            "email": "[e-mail]"
        }
    },
    "type": "Issue.Update",
    "tenant": {
        "id": 1
    }
}

• Response requirements after receiving a webhook:

After receiving an HTTP POST request, the application needs to respond to the request within 3 seconds with an HTTP 200 status code and the following JSON response body. Otherwise, this push will be considered a failure, and in the WebHooks-Send Records corresponding to the webhook, this request will be recorded as a failed request.

{
 "errcode": 0
 }

• Timeout Description:

Connection timeout: 3 seconds, request timeout: 3 seconds, total: 6 seconds.

Appendix 1: Template Variables