{"_id":"5d23e7bdae8464005cd66fe6","project":"564e5930c3553e0d003e53d0","version":{"_id":"564e5a9b1560880d008d30dc","project":"564e5930c3553e0d003e53d0","__v":27,"createdAt":"2015-11-19T23:26:19.166Z","releaseDate":"2015-11-19T23:26:19.166Z","categories":["564e5a9b1560880d008d30dd","566318e1f5ca460d00f41896","56631d08cd54d50d005015fa","56631d2a81ad7417006a202c","5668ba19fbd7680d009375f4","5668cb8b10bda80d00797ed9","5668cb9d10bda80d00797eda","56830d8a3f94e00d004e2a7a","56830d9072bb720d0091f594","56830d94cb4d190d0027698e","56830dc44aecbd0d00a464c5","569e90f3c9b43e0d00c4bab1","56a96d338791090d00113bab","56b12d8336d2580d00247877","56c36bf0a869d017002ea55b","56c36bf93d30210d00ea84bb","56c77749b935671700ff0304","56c7ab9e5652c217008e091a","56cb8bdad5c6241d00ef5e61","58aefce02470660f00b54539","58aefd0bebd7370f0078b954","59ca65ca4337830026edf24f","5c33cd9eb47ba20051ac8d64","5c33df728bec1d0063431c34","5c4783ef523219027055513a","5c4f35033400f3010203a999","5d1d0c9f19c3a0003aeb525a"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Foundation","version_clean":"2.0.0","version":"2"},"category":{"_id":"56c7ab9e5652c217008e091a","pages":["56c7ace6606ee717003c475d","56d3d6390b39260b008da477"],"project":"564e5930c3553e0d003e53d0","version":"564e5a9b1560880d008d30dc","__v":2,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-19T23:56:14.582Z","from_sync":false,"order":7,"slug":"webhooks","title":"Webhooks"},"user":"5c2ff7abcef0c602316e8234","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-07-09T01:02:53.329Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"For more information on adding Webhooks, please see our Knowledge Base article:\n\n[Webhooks](https://support.pagerduty.com/docs/webhooks)\n[block:api-header]\n{\n  \"title\": \"HTTP Authentication and Web Server Access\"\n}\n[/block]\nWebhooks can be sent to any publicly accessible web server, on any port, with or without encryption. They can include a username and password for HTTP basic authentication.\n\n## Specify a username and password\nIf your web server uses HTTP basic authentication, you can add the username and password to the URL before the host address. Special characters such as :::at::: in the password should be percent-encoded.\n\n**Example**: `http://username:password@app.acmemonitoring.com/pagerduty.php`\n\n## Webhook Ports\nIf you specify `http://` in your Endpoint URL, we will initiate a standard HTTP connection on port 80. Likewise, entering `https://` means we will attempt to make a secure connection on port 443. To override the default port, add a colon (`:`) after the host address with the desired port number.\n\n**Example**: `https://app.acmemonitoring.com:8443/pagerduty.php`\n\n## Restrict access to just PagerDuty IPs\n\nYou can view our list of IPs to whitelist [here](https://support.pagerduty.com/docs/whitelisting-ips#section-webhooks).\n\n## Can I use a self-signed certificate for webhooks?\n\nYes. Web servers presenting self-signed or expired certificates will receive webhooks.\n[block:api-header]\n{\n  \"title\": \"Temporary Blocks and Blacklisting\"\n}\n[/block]\nWhen a site goes down or responds with an error status, it is expected that events can't be received to your webhook, or that it will become completely disabled.\n\nWhen events are sent to your webhook endpoints, PagerDuty expects a 200 response within 5 seconds. If there is no response, or if there is any response other than a 200, PagerDuty will periodically retry sending the webhook. \n\n## Server and Network Errors\n\nIf we receive a 5XX (server error) response from the receiving end, or can't establish a connection, or can't resolve the host name, it is considered a transient issue and retry logic is applied. First the event is rescheduled for delivery 50 seconds in the future. If it continues to 500, PagerDuty will back off by a multiple of 1.25^N for 7 more tries (8 retries total). This takes about 20 minutes.\n\n## Client Errors\n\nIf we receive a 4XX (client error) response from the receiving end, the error is considered non-transient, and the webhook is dropped. If the number of dropped webhook events exceeds 8, the endpoint will be disabled.\n\n## Temporary Disablement\n\nAfter retries are exhausted or the maximum number of dropped webhook events is reached, the endpoint will be disabled for 30 minutes. PagerDuty will continue to accumulate events for the endpoint while it is disabled. Events will be scheduled for after the disable has expired. If the retries continue to fail, the endpoint will be disabled for exponentially longer periods of time (again, 1.25^N), up to 6 retries total (about 7.5 hours).\n\nIf PagerDuty still can't deliver a webhook event at that point, it will blacklist the endpoint and show that the webhook is disabled in the web app. Queued events will be discarded until a user manually unblocks it in the web UI.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/58d4118-Webhooks_2-webhook-disabled.jpg\",\n        \"Webhooks 2-webhook-disabled.jpg\",\n        1394,\n        221,\n        \"#ededed\"\n      ]\n    }\n  ]\n}\n[/block]\n## Classification of Endpoints\n\nOur webhook delivery service's retry/temporary blacklist logic groups and classifies webhooks according to their endpoint URL, and not by the service or distinct extension object itself. So, if you have two differently-named webhooks on two different services, but they both have the same endpoint URL, they will both be temporarily disabled if webhooks from one of them end up receiving error responses.\n[block:api-header]\n{\n  \"title\": \"Webhook IPs\"\n}\n[/block]\nSee our knowledge base article [Whitelisting IPs](https://support.pagerduty.com/docs/whitelisting-ips#section-webhooks) for information on obtaining the list of IPs webhooks may come from.","excerpt":"","slug":"webhook-behavior","type":"basic","title":"Webhook Behavior"}
For more information on adding Webhooks, please see our Knowledge Base article: [Webhooks](https://support.pagerduty.com/docs/webhooks) [block:api-header] { "title": "HTTP Authentication and Web Server Access" } [/block] Webhooks can be sent to any publicly accessible web server, on any port, with or without encryption. They can include a username and password for HTTP basic authentication. ## Specify a username and password If your web server uses HTTP basic authentication, you can add the username and password to the URL before the host address. Special characters such as @ in the password should be percent-encoded. **Example**: `http://username:password@app.acmemonitoring.com/pagerduty.php` ## Webhook Ports If you specify `http://` in your Endpoint URL, we will initiate a standard HTTP connection on port 80. Likewise, entering `https://` means we will attempt to make a secure connection on port 443. To override the default port, add a colon (`:`) after the host address with the desired port number. **Example**: `https://app.acmemonitoring.com:8443/pagerduty.php` ## Restrict access to just PagerDuty IPs You can view our list of IPs to whitelist [here](https://support.pagerduty.com/docs/whitelisting-ips#section-webhooks). ## Can I use a self-signed certificate for webhooks? Yes. Web servers presenting self-signed or expired certificates will receive webhooks. [block:api-header] { "title": "Temporary Blocks and Blacklisting" } [/block] When a site goes down or responds with an error status, it is expected that events can't be received to your webhook, or that it will become completely disabled. When events are sent to your webhook endpoints, PagerDuty expects a 200 response within 5 seconds. If there is no response, or if there is any response other than a 200, PagerDuty will periodically retry sending the webhook. ## Server and Network Errors If we receive a 5XX (server error) response from the receiving end, or can't establish a connection, or can't resolve the host name, it is considered a transient issue and retry logic is applied. First the event is rescheduled for delivery 50 seconds in the future. If it continues to 500, PagerDuty will back off by a multiple of 1.25^N for 7 more tries (8 retries total). This takes about 20 minutes. ## Client Errors If we receive a 4XX (client error) response from the receiving end, the error is considered non-transient, and the webhook is dropped. If the number of dropped webhook events exceeds 8, the endpoint will be disabled. ## Temporary Disablement After retries are exhausted or the maximum number of dropped webhook events is reached, the endpoint will be disabled for 30 minutes. PagerDuty will continue to accumulate events for the endpoint while it is disabled. Events will be scheduled for after the disable has expired. If the retries continue to fail, the endpoint will be disabled for exponentially longer periods of time (again, 1.25^N), up to 6 retries total (about 7.5 hours). If PagerDuty still can't deliver a webhook event at that point, it will blacklist the endpoint and show that the webhook is disabled in the web app. Queued events will be discarded until a user manually unblocks it in the web UI. [block:image] { "images": [ { "image": [ "https://files.readme.io/58d4118-Webhooks_2-webhook-disabled.jpg", "Webhooks 2-webhook-disabled.jpg", 1394, 221, "#ededed" ] } ] } [/block] ## Classification of Endpoints Our webhook delivery service's retry/temporary blacklist logic groups and classifies webhooks according to their endpoint URL, and not by the service or distinct extension object itself. So, if you have two differently-named webhooks on two different services, but they both have the same endpoint URL, they will both be temporarily disabled if webhooks from one of them end up receiving error responses. [block:api-header] { "title": "Webhook IPs" } [/block] See our knowledge base article [Whitelisting IPs](https://support.pagerduty.com/docs/whitelisting-ips#section-webhooks) for information on obtaining the list of IPs webhooks may come from.