Issues & Notifications

Issues let you track problems in your project and communicate resolution steps with your team.

How issues work

When a problem occurs, an issue is automatically opened per the connection's issue trigger and your team is notified per the project's notification preferences.

You can inspect an issue to understand its root cause and take steps to resolve it. This includes viewing all associated events, and replaying the affected events once the issue is fixed.

Along the way, it's good practice to mark the issue with the appropriate status to keep your team up-to-date on resolution measures.

Parts of an issue

Issue type

An issue's type represents the kind of problem that triggered it.

Issue typeBehavior
DeliveryA delivery issue is opened when an attempt results in failures, according to the connection's issue trigger. Delivery issues display a histogram of the associated events, as well as the option to bulk retry all the associated failures.
TransformationA transformation issue is opened when one of your transformations has failed to properly apply, either due to uncaught exceptions, thrown errors, or invalid data.
BackpressureA transformation issue is caused when the estimated queue time (600,000ms, or 10 minutes, by default) exceeds the configured delay threshold.

Issue status

Each issue has a status that helps you track resolution steps with your team.

Issue statusDescription
OpenA new issue that will display a red error badge on the dashboard
AcknowledgedAn ongoing issue that has been acknowledged by a project member
ResolvedAn issue that has been fixed, or is believed to have been fixed
IgnoredAn issue that will no longer re-open when it reoccurs (use with caution)

When setting the issue status to ignored, please be aware that equivalent errors on this connection will no longer trigger alerts.

Additionally, you can hide an issue from the UI by dismissing it. Dismissed issues will re-open when they reoccur unless they are also marked as ignored.

To reveal your dismissed issues, click the filter button at the top of the Issues page and toggle Include Dismissed.

Issue notifications

Automatically alert your team to any issues so they can begin to take steps to resolve problems as soon as possible.

To set up issue notifications, configure the project's notification preferences. Members can be alerted on two possible triggers:

  • When an issue is opened
  • When an issue's status is updated

Notifications contain the payload of the failed webhook.

View issues

Viewing issues gives you an overview of the problems occurring in your project. Each issue points to a specific problem and provides context for resolving it.

  1. Open the Issues page to see a list of all issues, grouped by status.

Dismissed issues are hidden by default.

  1. To view issues of only a specific type, click the Filter button in the top bar and items by the desired issue type.
  2. To show or hide issues by status, or to see dismissed issues, click the corresponding tab at the top of the page.

From the Issues page, you can update an issue's status, view a mini histogram of occurrences, and determine when this issue was first and last seen.

GET /issues

Inspect and issue

Inspecting an issue gives you access to its surrounding context, including associated events, so that you can take informed action on it.

  1. Find your issue on the Issues page.
  2. Click the issue's title.

From here you can see a chart of occurrences using the histogram, view all associated events by clicking View Events, or re-attempt delivery on the associated failures by clicking Bulk Retry.

GET /issues/:id

Update an issue

Updating an issue's status lets you communicate its resolution status to your team.

  1. Find your issue on the Issues page.
  2. Click the next to the issue's status.
  3. Select the issue's new status, or click Dismiss to hide the issue.
PUT /issues/:id

Issues marked resolved or dismissed will automatically re-open when they reoccur. To prevent this behavior, mark the issue as ignored.

Dismiss an issue

Dismissing an issue prevents it from appearing in your list of issues, which can help declutter your project.

  1. Find your issue on the Issues page.
  2. Click the next to the issue's status.
  3. Select Dismiss to hide the issue.
DELETE /issues/:id

Dismissed issues will re-open when they reoccur unless they are marked ignored before being dismissed.

Configure notifications

Configuring notifications lets your team receive email and/or webhook alerts when issues change in your project. These alerts allow for a more proactive approach to troubleshooting since you can take steps to resolve problems before they begin to impact users.

Notifications contain the payload of the failed webhook.

Configure email notifications

  1. Open the project settings page.
  2. Toggle the Email Notifications switch to the on position.
  3. Click Save.

Configure webhook notifications

  1. Open the project settings page.

  2. Toggle the Webhook Notifications switch to the on position.

  3. If enabling webhook notifications, select the desired topics in the Webhook topics section. An explanation of each topic can be found at the bottom of this page.

  4. If enabling webhook notifications, select the desired source in the Webhook source section. This source is where the webhook notifications will be sent.

    We recommend creating a source named hookdeck to receive these webhook notifications; delivery of these notifications to various destinations can then be managed by adding destinations to that source.

  5. Click Save.

PUT /notifications/webhooks

Notification topics

Notification topics define which event type(s) you want to receive notifications for.

Notification topicExplanation
issue.openedTriggers any time an issue is opened
issue.updatedTriggers any time an issue's status is updated
event.successfulTriggers any time an event is successful

The event.successful payload has the following structure where attempt_response contains the body content of the successul request to the destination::

{
  "topic": "event.successful",
  "event_id": "string",
  "event_data": {
    "body": {},
    "headers": {},
    "parsed_query": {},
    "path": "string",
    "query": "string",
    "is_large_payload": false
  },
  "attempt_id": "string",
  "attempt_response": {},
  "connection": {
    "id": "string",
    "name": "string",
    "full_name": "string",
    "source": {
      "id": "string",
      "name": "string"
    },
    "destination": {
      "id": "string",
      "name": "string"
    }
  }
}