From 2bbd565f2c9c88ef008825cb818adaf6d6743451 Mon Sep 17 00:00:00 2001
From: Danny Porrello <75634548+dannyporrello@users.noreply.github.com>
Date: Tue, 2 Jan 2024 17:59:10 -0500
Subject: [PATCH] AGX-2496/Webhooks-Documentation (#206)
* AGX-2496/Webhooks-Documentation
Adding possibility of `outcome` returning `discarded`. Also, changing the wording to show that flushed queue show as outcome `discarded` and not `failed` anymore.
* Adding discarded as a filter possibility.
---
webhooks/webhooks.md | 2 +-
webhooks/webhooks_api.md | 6 +++---
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/webhooks/webhooks.md b/webhooks/webhooks.md
index 0e0fa9e..5b54a75 100644
--- a/webhooks/webhooks.md
+++ b/webhooks/webhooks.md
@@ -136,7 +136,7 @@ One approach to handling this scenario is to log each processed event, and then
When a Webhook delivery fails, due to a failure to establish a connection to the destination URL, the destination returning a non-2XX response code, or the request timing out (5 seconds), all future deliveries to that endpoint will be paused.
The failing Webhook will then be retried using an exponential backoff scheme, starting with a 1 second interval and with a maximum interval of 1 hour.
-After 12 hours of retrying event delivery to that destination URL, the delivery queue will be flushed and all queued events will be marked as `failed`.
+After 12 hours of retrying event delivery to that destination URL, the delivery queue will be flushed and all queued events will be marked as `discarded`.
When the next new Webhook to be delivered is ready, it will attempt to deliver it from a fresh start, beginning a new retry cycle if the destination URL remains unavailable.
If at any point during the retry cycle a successful delivery occurs, the system will resume sending events as normal and all retry counters will be reset.
diff --git a/webhooks/webhooks_api.md b/webhooks/webhooks_api.md
index 3479eae..b1a6ca9 100644
--- a/webhooks/webhooks_api.md
+++ b/webhooks/webhooks_api.md
@@ -152,7 +152,7 @@ The following table describes the various attributes of the List Webhooks Delive
| response_headers | Object containing key/value pairs representing the HTTP header fields included in the response to the webhooks delivery POST call. |
| response_error | Error response message, if applicable. |
| response_body | Content of the HTTP response body resulting from the webhooks delivery POST call. |
-| outcome | Result for the webhooks event delivery attempt. Can be one of 'ok', 'retried', or 'failed'. |
+| outcome | Result for the webhooks event delivery attempt. Can be one of 'ok', 'discarded', 'retried', or 'failed'. |
| id | Unique identifier for the delivery. |
| event_id | Unique identifier for the webhooks event for which a delivery was attempted. |
| event | The event object containing the following properties:
- _user_id_ - ID for the User that initiated the event.
- _timestamp_ - UTC date/time when the event occurred.
- _resource_name_ - Name of the Resource in which the event occurred.
- _resource_id_ - ID for the Resource in which the event occurred.
- _project_id_ - ID of the Project in which the event occurred.
- _id_ - ID for the event.
- _event_type_ - Type of event - will be 'create', 'update', or 'delete'.
- _company_id_ - ID of the Company in which the event occurred.
- _api_version_ - Procore API version.
- _metadata_ - An object containing contextual information about the event.
- _ulid_ - Unique identifier encoded as a 26 character string. See [ULID specification](https://github.com/ulid/spec) for additional information. |
@@ -161,7 +161,7 @@ The following table describes the various attributes of the List Webhooks Delive
### Filtering the List Webhooks Deliveries Response
Due to the potential large volume of webhooks deliveries your system might be required to consume, you may find it helpful to filter the response from the List Webhooks Deliveries call using the `filters[status]` query parameter.
-This query parameter lets you limit the response to 'any' (default), 'successful', or 'failing' webhooks deliveries.
+This query parameter lets you limit the response to 'any' (default), 'successful', 'discarded', or 'failing' webhooks deliveries.
Here is the syntax for using the `filters[status]` query parameter.
```
@@ -169,7 +169,7 @@ https://api.procore.com/rest/v1.0/webhooks/hooks//deliveries?company_id
where: is the ID for webhook hook
is the ID for company (could also be )
- is the filter setting - either 'any', 'successful', or 'failing'
+ is the filter setting - either 'any', successful', 'discarded', or 'failing'
example: curl -X GET https://api.procore.com/rest/v1.0/webhooks/hooks/12345/deliveries?
company_id=987654&filter[status]=failing