List webhook subscription matched events

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "matches": [
    {
      "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "matchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "eventType": "onchain.activity.detected",
      "createdAt": "2025-01-15T10:30:00Z",
      "occurredAt": "2025-01-15T10:29:58Z",
      "succeededAt": "2025-01-15T10:30:02Z",
      "attemptCount": 1,
      "status": "succeeded",
      "payload": {
        "eventId": "00000000-0000-0000-0000-000000000000",
        "eventType": "onchain.activity.detected",
        "data": {
          "foo": "bar"
        }
      },
      "latestAttempt": {
        "result": "success",
        "attemptedAt": "2025-01-15T10:30:00Z",
        "statusCode": 200,
        "attemptNumber": 1,
        "requestHeaders": [
          {
            "name": "Content-Type",
            "value": "application/json"
          }
        ],
        "targetUrl": "https://example.com/webhook"
      }
    }
  ],
  "nextPageToken": "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
}

Webhooks

List webhook subscription matched events

Retrieve webhook events that match the subscriptionId specified.

Returns matches in descending order by creation time (newest first), including delivery status, retry count, next attempt time, and response details.

Only matched events are returned. Matched events are events that both:

Have the same eventType as defined in the subscription’s list of eventTypes.
Match all labels defined in the subscription’s labels.

If an event didn’t match the subscription’s labels or eventTypes, it will not be returned by this endpoint.

Use Cases

View all events for a subscription to inspect subscription health
Confirm that a target URL received all matched events successfully

Use eventId to find all matches for a specific event, including replays.

Use status to return only matches in a given delivery state, such as retrying matches that need attention.

Use pageSize to control the number of matched events returned and pageToken to retrieve subsequent pages.

GET

data

webhooks

subscriptions

{subscriptionId}

matches

List webhook subscription matched events

curl --request GET \
  --url https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cdp.coinbase.com/platform/v2/data/webhooks/subscriptions/{subscriptionId}/matches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "matches": [
    {
      "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "matchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "eventType": "onchain.activity.detected",
      "createdAt": "2025-01-15T10:30:00Z",
      "occurredAt": "2025-01-15T10:29:58Z",
      "succeededAt": "2025-01-15T10:30:02Z",
      "attemptCount": 1,
      "status": "succeeded",
      "payload": {
        "eventId": "00000000-0000-0000-0000-000000000000",
        "eventType": "onchain.activity.detected",
        "data": {
          "foo": "bar"
        }
      },
      "latestAttempt": {
        "result": "success",
        "attemptedAt": "2025-01-15T10:30:00Z",
        "statusCode": 200,
        "attemptNumber": 1,
        "requestHeaders": [
          {
            "name": "Content-Type",
            "value": "application/json"
          }
        ],
        "targetUrl": "https://example.com/webhook"
      }
    }
  ],
  "nextPageToken": "eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="
}

Authorizations

Authorization

string

header

required

A JWT signed using your CDP API Key Secret, encoded in base64. Refer to the Generate Bearer Token section of our Authentication docs for information on how to generate your Bearer Token.

Path Parameters

subscriptionId

string<uuid>

required

Unique identifier for the webhook subscription.

Pattern: ^[a-f0-9\-]{36}$

Query Parameters

pageSize

integer

default:50

The number of matches to return per page.

Required range: 1 <= x <= 1000

pageToken

string

The token for the next page of resources, if any.

eventId

string<uuid>

Filter by a specific event ID.

Pattern: ^[a-f0-9\-]{36}$

minCreatedAt

string<date-time>

Filter matched events created at or after this timestamp (RFC 3339 format).

maxCreatedAt

string<date-time>

Filter matched events created at or before this timestamp (RFC 3339 format).

eventTypes

string

Filter by event type names (comma-separated).

status

enum<string>

Filter matched events by status. Current state of the matched event.

retrying: The event is currently being retried. For when the next attempt will occur, see nextAttemptAt.
abandoned: The event was abandoned. This means the subscription was disabled during the retry lifecycle.
succeeded: The event was successfully delivered to the target URL.
failed: The event delivery failed due to reaching the maximum number of retry attempts or other non-retryable failure such as a subscription misconfiguration.

Available options:

retrying,

abandoned,

succeeded,

failed

Example:

"succeeded"

Response

Webhook events retrieved successfully.

Response containing a list of webhook events that match the subscriptionId specified.

matches

object[]

required

The list of webhook events that match the subscriptionId specified.

Events are sorted by createdAt in descending order (most recent first).

Show child attributes

nextPageToken

string

The token for the next page of items, if any.

Example:

"eyJsYXN0X2lkIjogImFiYzEyMyIsICJ0aW1lc3RhbXAiOiAxNzA3ODIzNzAxfQ=="