September 16th, 2020 | 2 minute read

Introducing OAuth Revocation Webhook Events

Making it easier to know when permissions have been revoked

Developers have struggled to navigate failed API calls when revoked access tokens are used, while not understanding which merchants unsubscribed to their application. We recently filled this gap, and are excited to announce the release of OAuth Revocation webhooks! OAuth revocation events make it easier for developers to respond when a connected merchant revokes all access tokens, or when an application revokes access/refresh tokens granted to it.

Revocation webhooks can help reduce occurrences of 401 Unauthorized errors due to revoked access tokens, and provide revocation visibility for purposes of security auditing and application usage analytics.

Our partner, Postmates - helped us understand the biggest struggles with their integration, and deliver an ideal solution. We’re excited to open this to all Square Partners as a Beta launch.

“One of the biggest pains we have is with OAuth access tokens. We need to know if the token is active or whether access has been revoked. There isn’t a way to do that today. Whenever we use a token - it can fail - and we have no way of knowing it is no longer valid before making the call. We are asking for a webhook response when a token is revoked.”
Andrew Mager | Senior Software Engineer | Postmates Inc.

Event payload

EVENT oauth.authorization.revoked

{
  "merchant_id": "J9Z30SF99NPFJ",
  "type": "oauth.authorization.revoked",
  "event_id": "e1d6ae37-5aa9-45a5-b525-b12caf819fdb",
  "created_at": "2020-08-14T15:51:04.246373287Z",
  "data": {
    "type": "revocation",
    "id": "415641cf-eba2-4dfa-88cc-c4be1301fdc6",
    "object": {
      "revocation": {
        "revoked_at": "2020-08-14T15:51:00.246373287Z",
        "revoker_type": "MERCHANT"
      }
    }
  }
}

What’s included

Subscribers will receive a published event when a merchant or application revokes all access tokens and refresh tokens granted to an application. This payload will include:

merchant_id: The ID of the target merchant associated with the event.
type: The type of event this represents, "oauth.authorization.revoked".
event_id: A unique ID for the webhook event.
created_at: Timestamp of when the webhook event was created, in RFC 3339 format.
data: Data associated with the event.