Events

Overview

Once your registrations are setup, event objects will be send to the URLs you've registered. An event object contains a list of resource identifiers, which can be used to download further detail on the subject of each event.

All events are delivered with the same standard format:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Account.Opened",
  "status": "Pending",
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2018-07-26T03:48:55.969Z",
  "lastAttemptedAt": "2018-07-26T04:45:15.128Z",
  "resources": [
    "core/v1/dda/accounts/2001231231",
    "core/v1/dda/accounts/2001231232",
  ]
}

One event object can represent many individual resource events. Event objects are typically aggregated every 30-120 seconds. In the above example, the event object refers to two deposit accounts which were recently opened, specified in the resources array field.

The status of Pending indicates the event was created, but we have not been able to deliver it yet. The status included in the event object does not represent the status of the resource. For example, in the sample event object above, the status of Pending does not mean that accounts 2001231231 and 20001231232 are pending. The status in the event object only pertains to the webhook event itself. Partner should always expect this status when receiving events. The only time partners will experience a status of Success is if they search events (using GET /webhooks/v1/events/{id} that have already been successfully delivered to the registered callback URL.

Once an attempt has been made, the status will transition to either Success once you acknowledge receipt or Failed if we are unable to successfully deliver the event to your callback URL. When you receive a webhook event, you can always expect the status to reflect as Pending.

Handling Failure

In the event something goes wrong and we cannot deliver an event to one of your registrations, we will make several retry attempts. If we still cannot deliver the event, the registration status will change to Suspended. No further attempts will be made to deliver previous or future events to this endpoint. It is very important to monitor the statuses of your webhook registrations. If you see a status of Suspended, you should first work to identify the issue by reviewing the logs of recent failed events.

Once the issue has been resolved, you may restart your registration using the webhooks API. At this point the status will transition to Restarting. If we can deliver an event successfully, the status will return to Active. If we cannot deliver at least one event successfully, then the status will return to Suspended.

❗️

Deleting a registration and subsequently re-registering for the same event should not be used to resolve an event delivery failure. Doing so will prevent your ability to retrieve any events that were queued for delivery, as well as any events that fired in the time between deletion and re-registration.

Also note that webhooks guarantee at-least-once delivery. So while rare, it is technically possible to receive the same event twice. Your message handlers should account for that edge case and be idempotent.

See the Webhook API reference for more details.