# Issues & Notifications Issues let you track problems in your project and communicate resolution steps with your team. Video: [Issues in Hookdeck Video](/videos/docs/hookdeck-issues-overview.mp4) ## How issues work When a problem occurs, an issue is automatically opened per the project's [issue triggers](/docs/issue-triggers) and your team is notified per the project's [notification preferences](#configure-notifications). You can [inspect an issue](#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](#update-an-issue) with the appropriate [status](#issue-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 status Each issue has a status that helps you track resolution steps with your team. | Issue status | Description | | --- | --- | | Open | A new issue that will display a red error badge on the dashboard | | Acknowledged | An ongoing issue that has been acknowledged by a project member | | Resolved | An issue that has been fixed, or is believed to have been fixed | | Ignored | An 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](#configure-notifications). 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. ### Dashboard 1. Open the [Issues](https://dashboard.hookdeck.com/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](#issue-type). 2. To show or hide issues by [status](#issue-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](#update-an-issue), view a mini histogram of occurrences, and determine when this issue was first and last seen. ### API `GET /2025-07-01/issues` **Response example** ```json { "pagination": { "order_by": "created_at", "dir": "desc", "limit": 100 }, "count": 1, "models": [ { "id": "iss_nLxlgkpe2GpkcSTtMt", "team_id": "tm_lbhzBKgFOUnB", "type": "delivery", "status": "OPENED", "aggregation_keys": { "error_code": [], "webhook_id": [ "web_nOYiSWuNW8EF" ], "response_status": [ 500 ] }, "reference": { "event_id": "evt_eNycCNgd99CGUBflic", "attempt_id": "atm_TgM9dDa4KzwKPmnnzuXA", "attempt_body": { "message": "The Mock API returns the request data with a HTTP 500 code", "next_step": "Convinced? Update your destination with your own server HTTP URL.", "received_data": { "body": { "body": { "type": "order.created", "total": 99.99, "customer": { "id": "cust_123", "email": "customer@example.com" }, "timestamp": "2026-01-14T13:35:55.335Z" }, "headers": { "content-type": "application/json" } }, "query": { "status": "500" }, "method": "POST", "headers": { "via": "1.1 google", "host": "mock.hookdeck.com", "accept": "application/json, text/plain, */*", "connection": "Keep-Alive", "user-agent": "axios/1.11.0", "content-type": "application/json", "content-length": "192", "accept-encoding": "gzip, compress, deflate, br", "idempotency-key": "evt_eNycCNgd99CGUBflic", "x-forwarded-for": "24.222.229.208, 34.36.135.20", "x-forwarded-proto": "https", "x-hookdeck-eventid": "evt_eNycCNgd99CGUBflic", "x-hookdeck-verified": "false", "x-hookdeck-event-url": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "x-hookdeck-requestid": "req_eLU3Rb3wyAfHpbRgrDIW", "x-hookdeck-signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "x-cloud-trace-context": "7b79cbbeb30598a3646e743a2cf61f55/10630529597864032755", "x-hookdeck-original-ip": "::1", "x-hookdeck-source-name": "example", "x-hookdeck-attempt-count": "1", "x-hookdeck-attempt-trigger": "INITIAL", "x-hookdeck-connection-name": "", "x-hookdeck-destination-name": "mock-api-failure", "x-hookdeck-will-retry-after": "" } }, "requested_path": "/" } }, "last_updated_by": null, "merged_with": null, "first_seen_at": "2026-01-14T13:35:55.736Z", "last_seen_at": "2026-01-14T13:35:55.736Z", "dismissed_at": null, "opened_at": "2026-01-14T13:35:55.736Z", "updated_at": "2026-01-14T13:35:55.737Z", "created_at": "2026-01-14T13:35:55.737Z", "issue_trigger_id": "it_XsLswYZ6nLMdze", "auto_resolved_at": null } ] } ``` ## 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. ### Dashboard 1. [Find your issue](#view-issues) 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. For request issues, you can view the rejected request's metadata, HTTP details, and bulk retry rejected requests. ### API `GET /2025-07-01/issues/:id` **Response example** ```json { "id": "iss_nLxlgkpe2GpkcSTtMt", "team_id": "tm_lbhzBKgFOUnB", "type": "delivery", "status": "OPENED", "aggregation_keys": { "error_code": [], "webhook_id": [ "web_nOYiSWuNW8EF" ], "response_status": [ 500 ] }, "reference": { "event_id": "evt_eNycCNgd99CGUBflic", "attempt_id": "atm_TgM9dDa4KzwKPmnnzuXA", "attempt_body": { "message": "The Mock API returns the request data with a HTTP 500 code", "next_step": "Convinced? Update your destination with your own server HTTP URL.", "received_data": { "body": { "body": { "type": "order.created", "total": 99.99, "customer": { "id": "cust_123", "email": "customer@example.com" }, "timestamp": "2026-01-14T13:35:55.335Z" }, "headers": { "content-type": "application/json" } }, "query": { "status": "500" }, "method": "POST", "headers": { "via": "1.1 google", "host": "mock.hookdeck.com", "accept": "application/json, text/plain, */*", "connection": "Keep-Alive", "user-agent": "axios/1.11.0", "content-type": "application/json", "content-length": "192", "accept-encoding": "gzip, compress, deflate, br", "idempotency-key": "evt_eNycCNgd99CGUBflic", "x-forwarded-for": "24.222.229.208, 34.36.135.20", "x-forwarded-proto": "https", "x-hookdeck-eventid": "evt_eNycCNgd99CGUBflic", "x-hookdeck-verified": "false", "x-hookdeck-event-url": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "x-hookdeck-requestid": "req_eLU3Rb3wyAfHpbRgrDIW", "x-hookdeck-signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "x-cloud-trace-context": "7b79cbbeb30598a3646e743a2cf61f55/10630529597864032755", "x-hookdeck-original-ip": "::1", "x-hookdeck-source-name": "example", "x-hookdeck-attempt-count": "1", "x-hookdeck-attempt-trigger": "INITIAL", "x-hookdeck-connection-name": "", "x-hookdeck-destination-name": "mock-api-failure", "x-hookdeck-will-retry-after": "" } }, "requested_path": "/" } }, "last_updated_by": null, "merged_with": null, "first_seen_at": "2026-01-14T13:35:55.736Z", "last_seen_at": "2026-01-14T13:35:55.736Z", "dismissed_at": null, "opened_at": "2026-01-14T13:35:55.736Z", "updated_at": "2026-01-14T13:35:55.737Z", "created_at": "2026-01-14T13:35:55.737Z", "issue_trigger_id": "it_XsLswYZ6nLMdze", "auto_resolved_at": null, "data": { "trigger_event": { "webhook_id": "web_nOYiSWuNW8EF", "team_id": "tm_lbhzBKgFOUnB", "source_id": "src_32qkficffmdlme", "destination_id": "des_cWwBe16NUh9h", "event_data_id": "edt_sZp4bwt9En2j1FA6RnLd", "request_id": "req_eLU3Rb3wyAfHpbRgrDIW", "cli_id": null, "ingested_at": "2026-01-14T13:35:55.341Z", "attempts": 1, "status": "FAILED", "state": "NONE", "last_pending_at": "2026-01-14T13:35:55.404Z", "next_attempt_meta": null, "id": "evt_eNycCNgd99CGUBflic", "last_attempt_at": "2026-01-14T13:35:55.444Z", "next_attempt_at": null, "response_status": 500, "error_code": null, "successful_at": null, "issue_ids": [ "iss_nLxlgkpe2GpkcSTtMt" ], "created_at": "2026-01-14T13:35:55.397439Z", "updated_at": "2026-01-14T13:35:55.742271Z", "data": { "method": "POST", "url": "https://mock.hookdeck.com?status=500", "headers": { "Accept": "application/json, text/plain, */*", "Idempotency-Key": "evt_eNycCNgd99CGUBflic", "content-length": "192", "content-type": "application/json", "user-agent": "axios/1.11.0", "X-Hookdeck-Signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "X-Hookdeck-EventID": "evt_eNycCNgd99CGUBflic", "X-Hookdeck-RequestID": "req_eLU3Rb3wyAfHpbRgrDIW", "X-Hookdeck-Original-IP": "::1", "X-Hookdeck-Verified": "false", "X-Hookdeck-Event-URL": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "X-Hookdeck-Source-Name": "example", "X-Hookdeck-Connection-Name": "", "X-Hookdeck-Destination-Name": "mock-api-failure", "X-Hookdeck-Attempt-Count": "2", "X-Hookdeck-Attempt-Trigger": "MANUAL", "X-Hookdeck-Will-Retry-After": "" }, "body": { "headers": { "content-type": "application/json" }, "body": { "type": "order.created", "customer": { "id": "cust_123", "email": "customer@example.com" }, "total": 99.99, "timestamp": "2026-01-14T13:35:55.335Z" } }, "raw_body": "{\"headers\":{\"content-type\":\"application/json\"},\"body\":{\"type\":\"order.created\",\"customer\":{\"id\":\"cust_123\",\"email\":\"customer@example.com\"},\"total\":99.99,\"timestamp\":\"2026-01-14T13:35:55.335Z\"}}", "appended_headers": [ "Accept", "Idempotency-Key", "X-Hookdeck-Signature", "X-Hookdeck-EventID", "X-Hookdeck-RequestID", "X-Hookdeck-Original-IP", "X-Hookdeck-Verified", "X-Hookdeck-Event-URL", "X-Hookdeck-Source-Name", "X-Hookdeck-Connection-Name", "X-Hookdeck-Destination-Name", "X-Hookdeck-Attempt-Count", "X-Hookdeck-Attempt-Trigger", "X-Hookdeck-Will-Retry-After" ], "path": "", "query": "status=500", "parsed_query": { "status": "500" } } }, "trigger_attempt": { "team_id": "tm_lbhzBKgFOUnB", "event_id": "evt_eNycCNgd99CGUBflic", "destination_id": "des_cWwBe16NUh9h", "attempt_number": 1, "status": "FAILED", "response_status": 500, "error_code": null, "successful_at": null, "delivered_at": "2026-01-14T13:35:55.444Z", "delivery_latency": 40, "responded_at": "2026-01-14T13:35:55.652Z", "response_latency": 208, "trigger": "INITIAL", "state": "COMPLETED", "id": "atm_TgM9dDa4KzwKPmnnzuXA", "created_at": "2026-01-14T13:35:55.682554Z", "updated_at": "2026-01-14T13:35:55.682554Z", "body": { "message": "The Mock API returns the request data with a HTTP 500 code", "next_step": "Convinced? Update your destination with your own server HTTP URL.", "received_data": { "body": { "body": { "type": "order.created", "total": 99.99, "customer": { "id": "cust_123", "email": "customer@example.com" }, "timestamp": "2026-01-14T13:35:55.335Z" }, "headers": { "content-type": "application/json" } }, "query": { "status": "500" }, "method": "POST", "headers": { "via": "1.1 google", "host": "mock.hookdeck.com", "accept": "application/json, text/plain, */*", "connection": "Keep-Alive", "user-agent": "axios/1.11.0", "content-type": "application/json", "content-length": "192", "accept-encoding": "gzip, compress, deflate, br", "idempotency-key": "evt_eNycCNgd99CGUBflic", "x-forwarded-for": "24.222.229.208, 34.36.135.20", "x-forwarded-proto": "https", "x-hookdeck-eventid": "evt_eNycCNgd99CGUBflic", "x-hookdeck-verified": "false", "x-hookdeck-event-url": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "x-hookdeck-requestid": "req_eLU3Rb3wyAfHpbRgrDIW", "x-hookdeck-signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "x-cloud-trace-context": "7b79cbbeb30598a3646e743a2cf61f55/10630529597864032755", "x-hookdeck-original-ip": "::1", "x-hookdeck-source-name": "example", "x-hookdeck-attempt-count": "1", "x-hookdeck-attempt-trigger": "INITIAL", "x-hookdeck-connection-name": "", "x-hookdeck-destination-name": "mock-api-failure", "x-hookdeck-will-retry-after": "" } }, "requested_path": "/" } } } } ``` ## Update an issue Updating an issue's status lets you communicate its resolution status to your team. ### Dashboard 1. [Find your issue](#view-issues) 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. ### API `PUT /2025-07-01/issues/:id` **Request body example** ```json { "status": "RESOLVED" } ``` **Response example** ```json { "id": "iss_nLxlgkpe2GpkcSTtMt", "team_id": "tm_lbhzBKgFOUnB", "type": "delivery", "status": "RESOLVED", "aggregation_keys": { "error_code": [], "webhook_id": [ "web_nOYiSWuNW8EF" ], "response_status": [ 500 ] }, "reference": { "event_id": "evt_eNycCNgd99CGUBflic", "attempt_id": "atm_TgM9dDa4KzwKPmnnzuXA", "attempt_body": { "message": "The Mock API returns the request data with a HTTP 500 code", "next_step": "Convinced? Update your destination with your own server HTTP URL.", "received_data": { "body": { "body": { "type": "order.created", "total": 99.99, "customer": { "id": "cust_123", "email": "customer@example.com" }, "timestamp": "2026-01-14T13:35:55.335Z" }, "headers": { "content-type": "application/json" } }, "query": { "status": "500" }, "method": "POST", "headers": { "via": "1.1 google", "host": "mock.hookdeck.com", "accept": "application/json, text/plain, */*", "connection": "Keep-Alive", "user-agent": "axios/1.11.0", "content-type": "application/json", "content-length": "192", "accept-encoding": "gzip, compress, deflate, br", "idempotency-key": "evt_eNycCNgd99CGUBflic", "x-forwarded-for": "24.222.229.208, 34.36.135.20", "x-forwarded-proto": "https", "x-hookdeck-eventid": "evt_eNycCNgd99CGUBflic", "x-hookdeck-verified": "false", "x-hookdeck-event-url": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "x-hookdeck-requestid": "req_eLU3Rb3wyAfHpbRgrDIW", "x-hookdeck-signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "x-cloud-trace-context": "7b79cbbeb30598a3646e743a2cf61f55/10630529597864032755", "x-hookdeck-original-ip": "::1", "x-hookdeck-source-name": "example", "x-hookdeck-attempt-count": "1", "x-hookdeck-attempt-trigger": "INITIAL", "x-hookdeck-connection-name": "", "x-hookdeck-destination-name": "mock-api-failure", "x-hookdeck-will-retry-after": "" } }, "requested_path": "/" } }, "last_updated_by": null, "merged_with": null, "first_seen_at": "2026-01-14T13:35:55.736Z", "last_seen_at": "2026-01-14T13:35:55.736Z", "dismissed_at": null, "opened_at": "2026-01-14T13:35:55.736Z", "updated_at": "2026-01-14T13:36:41.432Z", "created_at": "2026-01-14T13:35:55.737Z", "issue_trigger_id": "it_XsLswYZ6nLMdze", "auto_resolved_at": null } ``` > 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. ### Dashboard 1. [Find your issue](#view-issues) on the Issues page. 2. Click the ⌄ next to the issue's status. 3. Select Dismiss to hide the issue. ### API `DELETE /2025-07-01/issues/:id` **Response example** ```json { "id": "iss_nLxlgkpe2GpkcSTtMt", "team_id": "tm_lbhzBKgFOUnB", "type": "delivery", "status": "RESOLVED", "aggregation_keys": { "error_code": [], "webhook_id": [ "web_nOYiSWuNW8EF" ], "response_status": [ 500 ] }, "reference": { "event_id": "evt_eNycCNgd99CGUBflic", "attempt_id": "atm_TgM9dDa4KzwKPmnnzuXA", "attempt_body": { "message": "The Mock API returns the request data with a HTTP 500 code", "next_step": "Convinced? Update your destination with your own server HTTP URL.", "received_data": { "body": { "body": { "type": "order.created", "total": 99.99, "customer": { "id": "cust_123", "email": "customer@example.com" }, "timestamp": "2026-01-14T13:35:55.335Z" }, "headers": { "content-type": "application/json" } }, "query": { "status": "500" }, "method": "POST", "headers": { "via": "1.1 google", "host": "mock.hookdeck.com", "accept": "application/json, text/plain, */*", "connection": "Keep-Alive", "user-agent": "axios/1.11.0", "content-type": "application/json", "content-length": "192", "accept-encoding": "gzip, compress, deflate, br", "idempotency-key": "evt_eNycCNgd99CGUBflic", "x-forwarded-for": "24.222.229.208, 34.36.135.20", "x-forwarded-proto": "https", "x-hookdeck-eventid": "evt_eNycCNgd99CGUBflic", "x-hookdeck-verified": "false", "x-hookdeck-event-url": "http://localhost:3000/events/evt_eNycCNgd99CGUBflic", "x-hookdeck-requestid": "req_eLU3Rb3wyAfHpbRgrDIW", "x-hookdeck-signature": "z73yK7iH8/YjGgA6ozLojgTk7/AxJZHy4hOVOQhMujs=", "x-cloud-trace-context": "7b79cbbeb30598a3646e743a2cf61f55/10630529597864032755", "x-hookdeck-original-ip": "::1", "x-hookdeck-source-name": "example", "x-hookdeck-attempt-count": "1", "x-hookdeck-attempt-trigger": "INITIAL", "x-hookdeck-connection-name": "", "x-hookdeck-destination-name": "mock-api-failure", "x-hookdeck-will-retry-after": "" } }, "requested_path": "/" } }, "last_updated_by": null, "merged_with": null, "first_seen_at": "2026-01-14T13:35:55.736Z", "last_seen_at": "2026-01-14T13:35:55.736Z", "dismissed_at": "2026-01-14T13:36:41.455Z", "opened_at": "2026-01-14T13:35:55.736Z", "updated_at": "2026-01-14T13:36:41.455Z", "created_at": "2026-01-14T13:35:55.737Z", "issue_trigger_id": "it_XsLswYZ6nLMdze", "auto_resolved_at": null } ``` 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. Supported notification channels include: * Email * Webhook * Slack * Discord * Microsoft Teams * PagerDuty * OpsGenie * Better Stack Uptime Slack, Discord, Microsoft Teams, PagerDuty, OpsGenie, and Better Stack Uptime are enabled via [Dashboard -> Project -> Integrations](https://dashboard.hookdeck.com/settings/project/integrations) and, where applicable, configured within the [Dashboard -> Project -> Issue Triggers](https://dashboard.hookdeck.com/issue-triggers) section. ### Configure email notifications 1. Open the [project settings](https://dashboard.hookdeck.com/settings/project/general) in the dashboard. 2. Toggle the Email Notifications switch to the on position. 3. Click Save. ### Configure webhook notifications ### Dashboard 1. Open the [project settings](https://dashboard.hookdeck.com/settings/project/general) 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](/docs/sources#create-a-source) named hookdeck to receive these webhook notifications; delivery of these notifications to various destinations can then be managed by [adding destinations](/docs/destinations#create-a-destination) to that source. 5. Click Save. ### API `PUT /2025-07-01/notifications/webhooks` **Request body example** ```json { "enabled": true, "topics": [ "issue.opened" ], "source_id": "src_qa5626p6y5o79b" } ``` **Response example** ```json { "enabled": true, "topics": [ "issue.opened" ], "source_id": "src_qa5626p6y5o79b" } ``` ### Notification topics Notification topics define which event type(s) you want to receive notifications for. | Notification topic | Explanation | | --- | --- | | `issue.opened` | Triggers any time an issue is opened | | `issue.updated` | Triggers any time an issue's status is updated | | `event.successful` | Triggers 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:: ```json { "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" } } } ``` ## Troubleshooting ### Why am I not receiving notifications for delivery failures or timeouts? Hookdeck automatically sends notifications when a delivery issue is triggered. However, there are several reasons why you might not receive a notification. 1. Project notifications are disabled Go to the Notification Settings section in your [project settings](https://dashboard.hookdeck.com/settings/project/general) and confirm that notifications for your desired channel type are turned on. 2. The delivery issue was ignored Hookdeck will not re-notify you about a delivery issue that has previously been ignored using the "Ignore" action If the same error occurs again (e.g. repeated timeouts or the same 5xx error), it will not trigger a new notification unless the previous issue is resolved, dismissed, or unignored. 3. The issue trigger is misconfigured * Check your [issue trigger configuration](https://dashboard.hookdeck.com/issue-triggers) under Issues → Issue Triggers * Ensure the desired notification channel is enabled 4. The email was filtered If the email notification channel was selected, make sure the notification wasn't caught by a spam or filter rule in your email client. #### Still not receiving notifications? If you've verified the above and are still not receiving expected alerts, contact [support@hookdeck.com](mailto:support@hookdeck.com) with the following details: * A link to the delivery or event in question * A screenshot of your notification settings * A screenshot of any ignored issues Our support team will help you investigate further.