# Event Webhook `Events` are triggered by changes in objects you've created via the API. Every time an `Event` related to one of your objects is created, EasyPost guarantees at least one POST request will be sent to each of the webhook URLs set up for your account. For this reason, we strongly encourage your webhook handler to be idempotent. See the webhooks guide for more information. --- ## Possible Event Types ### Batch - A "batch.created" `Event` is created when the initial creation of a `Batch` object is complete. - A "batch.updated" `Event` is created whenever the status of a `Batch` object changes. ### Claims - A "claims.submitted" `Event` is created when a claim is submitted through the EasyPost claim form or via the API. - A "claims.cancelled" `Event` is created when an existing claim is cancelled, either through a customer request or by EasyPost due to eligibility or processing requirements. - A "claims.updated" `Event` is created whenever the status or details of an in-progress claim change. This includes updates triggered by incoming customer correspondence or responses from EasyPost's claims team. - A "claims.rejected" `Event` is created when a claim is denied due to ineligibility, insufficient documentation, policy restrictions, or other disqualifying conditions. - A "claims.approved" `Event` is created when a claim is approved, either partially or in full, based on the reimbursable amount determined during claim review. ### Insurance - An "insurance.purchased" `Event` is created whenever a standalone `Insurance` completes purchasing and reporting to the insurer. - An "insurance.cancelled" `Event` is created whenever a standalone `Insurance` fails purchasing, is refunded to your account balance, and is not reported to the insurer. ### Payment - A “payment.created” `Event` is created when a bank account or credit card is successfully charged for a transaction that generates a `PaymentLog`. This includes charges used to fund the EasyPost wallet. For credit card charges, this event indicates that the charge is complete and the account balance has already been updated. For bank account transfers (ACH), this event indicates that the transfer process has begun; the transfer may still fail at a later stage. - A "payment.completed" `Event` is created when a bank account transfer is successfully completed and credited to your account balance. This event indicates that the accounting for that transfer is now complete. - A "payment.failed" `Event` is created when a bank account transfer or credit card charge has an issue and cannot be completed. For bank account transfers that fail your account balance may see a failure deduction and an EasyPost could possibly need to get in contact with you about your account status. ### Refund - A "refund.successful" `Event` is created whenever a non-instantaneous `Refund` request is completed. USPS is the best example of this, as USPS postage takes up to 15 days to be refunded after the initial refund creation. ### Report - A "report.new" `Event` is created when a `Report` object is initially created. The report won't be immediately ready for download. - A "report.empty" `Event` is created when a `Report` did not generate because there was no data in the specified date range. - A "report.available" `Event` is created when a `Report` becomes available to download. - A "report.failed" `Event` is created when a `Report` fails to generate. ### ScanForm - A "scan_form.created" `Event` is created when the initial creation of a `ScanForm` object is complete. - A "scan_form.updated" `Event` is created whenever the status of a `ScanForm` object changes. ### Shipment Invoice - A "shipment.invoice.created" `Event` is created when a `ShipmentInvoice` object is initially created. - A "shipment.invoice.updated" `Event` is created if a `ShipmentInvoice` is adjusted and updated. ### Tracker - A "tracker.created" `Event` is created when the initial creation of a `Tracker` object is complete. - A "tracker.updated" `Event` is created whenever a `Tracker` object gets successfully updated. --- ## Event object | Property | Type | Description | |----------|------|-------------| | object | string | "Event" | | mode | string | "test" or "production" | | description | string | Result type and event name. See Possible Event Types for more information. | | previous_attributes | object | Previous values of relevant result attributes | | result | object | The object associated with the Event. See the object attribute on the result to determine its specific type. This field will not be returned when retrieving events directly from the API. | | status | string | The current status of the event. Possible values: "completed" "failed" "in_queue" "retrying" | | pending_urls | string array | Webhook URLs that have not yet been successfully notified as of the time this webhook event was sent. The URL receiving the Event will still be listed in pending_urls, as will any other URLs that receive the Event at the same time. | | completed_urls | string array | Webhook URLs that have already been successfully notified as of the time this webhook was sent | | created_at | datetime | When the Event was created | | updated_at | datetime | When the Event was last updated | Example Object: ```json { "mode": "production", "description": "batch.created", "previous_attributes": { "state": "purchasing" }, "pending_urls": ["example.com/easypost-webhook"], "completed_urls": [], "created_at": "2015-12-03T19:09:19Z", "updated_at": "2015-12-03T19:09:19Z", "result": { "id": "batch_...", "object": "Batch", "mode": "production", "state": "purchased", "num_shipments": 1, "reference": null, "created_at": "2015-12-03T19:09:19Z", "updated_at": "2015-12-03T19:09:19Z", "scan_form": null, "shipments": [ { "batch_status": "postage_purchased", "batch_message": null, "id": "shp_a5b1348307694736aaqqqq8fqda53f93" } ], "status": { "created": 0, "queued_for_purchase": 0, "creation_failed": 0, "postage_purchased": 1, "postage_purchase_failed": 0 }, "pickup": null, "label_url": null }, "id": "evt_...", "object": "Event" } ``` --- ## Retrieve all Events ### Example: GET /events #### cURL ```shell curl -X GET "https://api.easypost.com/v2/events?page_size=5" \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func list() { client := easypost.New("EASYPOST_API_KEY") events, _ := client.ListEvents( &easypost.ListOptions{ PageSize: 5, }, ) fmt.Println(events) } ``` #### Java ```java package events; import com.easypost.exception.EasyPostException; import com.easypost.model.EventCollection; import com.easypost.service.EasyPostClient; import java.util.HashMap; public class All { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); HashMap params = new HashMap<>(); params.put("page_size", 5); EventCollection events = client.event.all(params); System.out.println(events); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Parameters.Event.All parameters = new() { PageSize = 5, }; EasyPost.Models.API.EventCollection events = await client.Event.All(parameters); Console.WriteLine(JsonConvert.SerializeObject(events, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const events = await client.Event.all({ page_size: 5, }); console.log(events); })(); ``` #### PHP ```php event->all([ 'page_size' => 5 ]); echo $events; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") events = client.event.all(page_size=5) print(events) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') events = client.event.all( page_size: 5, ) puts events ``` A list of all `Event` objects associated with the given `API Key` can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available. --- ## Retrieve an Event ### Example: GET /events/:id #### cURL ```shell curl -X GET https://api.easypost.com/v2/events/evt_... \ -u "EASYPOST_API_KEY": ``` #### Go ```go package example import ( "fmt" "github.com/EasyPost/easypost-go/v5" ) func retrieve() { client := easypost.New("EASYPOST_API_KEY") event, _ := client.GetEvent("evt_...") fmt.Println(event) } ``` #### Java ```java package events; import com.easypost.exception.EasyPostException; import com.easypost.model.Event; import com.easypost.service.EasyPostClient; public class Retrieve { public static void main(String[] args) throws EasyPostException { EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY"); Event event = client.event.retrieve("evt_..."); System.out.println(event); } } ``` #### C# ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using EasyPost; using Newtonsoft.Json; namespace EasyPostExamples { public class Examples { public static async Task Main() { var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY")); EasyPost.Models.API.Event @event = await client.Event.Retrieve("evt_..."); Console.WriteLine(JsonConvert.SerializeObject(@event, Formatting.Indented)); } } } ``` #### Node.js ```javascript const EasyPostClient = require('@easypost/api'); const client = new EasyPostClient('EASYPOST_API_KEY'); (async () => { const event = await client.Event.retrieve('evt_...'); console.log(event); })(); ``` #### PHP ```php event->retrieve('evt_...'); echo $event; ``` #### Python ```python import easypost client = easypost.EasyPostClient("EASYPOST_API_KEY") event = client.event.retrieve("evt_...") print(event) ``` #### Ruby ```ruby require 'easypost' client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY') event = client.event.retrieve('evt_...') puts event ``` An `Event` can be retrieved by its `id`.