Error handling and recovery

You may need to act on problematic webhooks in two main cases: resending those that errored or replaying those that were missed.

Resending errored webhooks

Webhooks enter an error state once the Tuum system reaches the maximum retry limit for delivery. This occurs when there is a network or destination-system malfunction.

By following the steps below, you can retry sending any webhooks that still need to be sent and ignore those that do not.

1

Find errored webhooks

To retrieve the full list of webhooks in an ERROR state, use the Search notifications endpoint with the query parameters statusCodes=ERROR and channelCode=WEBHOOK.

Shell (bash)

curl -L 'https://notification-api.sandbox.tuumplatform.com/api/v1/notifications?statusCodes=ERROR&channelCode=WEBHOOK&pageSize=100&pageNumber=1' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMDcxIiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI2LTAyLTA2VDEwOjA0OjI1IiwiZXhwIjoxNzcwMzcyMjY1LCJyb2xlcyI6WyJBRE1JTiIsIkRBU0hCT0FSRF9CQUxBTkNFX1ZJRVdFUiIsIlNZU1RFTSJdfQ.3VfcmyxuZj4JHfOll1Bw1yloxkwd-iFWD7_A-9JlBsI' \
-d ''

2

Retry sending

Parse the response from step 1 and fetch the notificationId value for the webhooks you want to retry.

Use the Retry sending errored notification endpoint and specify a notificationId in the path to retry the selected errored notification.

Shell (bash)

curl -L -X POST 'https://notification-api.sandbox.tuumplatform.com/api/v1/notifications/ID-259759/retry' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMDcxIiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI2LTAyLTA2VDEwOjA0OjI1IiwiZXhwIjoxNzcwMzcyMjY1LCJyb2xlcyI6WyJBRE1JTiIsIkRBU0hCT0FSRF9CQUxBTkNFX1ZJRVdFUiIsIlNZU1RFTSJdfQ.3VfcmyxuZj4JHfOll1Bw1yloxkwd-iFWD7_A-9JlBsI' \
-d ''

You can skip this step if you do not need any failed webhooks to be resent.

3

Ignore those that do not require resending

Parse the response from step 1 and retrieve the notificationId values for each webhook you plan to ignore.

Use the Ignore notifications in the error endpoint and list an array of notificationId values in the payload to clear the error status from selected errored notifications you do not intend to resend.

Shell (bash)

curl -L 'https://notification-api.sandbox.tuumplatform.com/api/v1/notifications/ignore' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMDcxIiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI2LTAyLTA2VDEwOjA0OjI1IiwiZXhwIjoxNzcwMzcyMjY1LCJyb2xlcyI6WyJBRE1JTiIsIkRBU0hCT0FSRF9CQUxBTkNFX1ZJRVdFUiIsIlNZU1RFTSJdfQ.3VfcmyxuZj4JHfOll1Bw1yloxkwd-iFWD7_A-9JlBsI' \
-H 'Content-Type: application/json' \
-d '{
  "notificationIds": [
    "ID-259808",
    "ID-259806",
    "ID-259804"
  ]
}'

You can skip this step if you do not plan to ignore any errored webhook.

Replaying missed webhooks

If you discover you missed a webhook that the Tuum system successfully sent, you can resend it.

Follow these steps to replay the notification and resend the webhook.

1

Identify missed webhooks

Use the Search notifications endpoint with the right query parameters to retrieve a limited number of webhooks. This helps you identify the missed webhook faster.

2

Replay notification for webhook resending

Parse the response from step 1 and fetch the notificationId value for the webhooks you want to replay.

Use the Replay notification endpoint and specify a notificationId in the path to resend the selected webhook.

Shell (bash)

curl -L -X POST 'https://notification-api.sandbox.tuumplatform.com/api/v1/notifications/ID-259785/retry' \
-H 'x-auth-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiTGlpdmEgS2FzdCIsImVtcGxveWVlSWQiOiJJRC0xMDcxIiwidGVuYW50Q29kZSI6Ik1CIiwiZXhwaXJ5RFRpbWUiOiIyMDI2LTAyLTA2VDExOjA2OjU5IiwiZXhwIjoxNzcwMzc2MDE5LCJyb2xlcyI6WyJBRE1JTiIsIkRBU0hCT0FSRF9CQUxBTkNFX1ZJRVdFUiIsIlNZU1RFTSJdfQ.RH-YeP5bEBOKvbyU3fcCV-wfUUKnwgoQXcBGjoMh5MM' \
-d ''