Skip to content

WebhooksEventsApi.md

Latest commit

 

History

History
755 lines (524 loc) · 22.4 KB

WebhooksEventsApi.md

File metadata and controls

755 lines (524 loc) · 22.4 KB
Raw

WebhooksEventsApi

All URIs are relative to https://up.go-adserver.com

Method HTTP request Description
apiV1EventsGet GET /api/v1/events Read the account's event feed.
apiV1WebhooksGet GET /api/v1/webhooks List webhooks.
apiV1WebhooksIdDelete DELETE /api/v1/webhooks/{id} Remove a webhook.
apiV1WebhooksIdDeliveriesDeliveryRedeliverPost POST /api/v1/webhooks/{id}/deliveries/{delivery}/redeliver Send a delivery again.
apiV1WebhooksIdDeliveriesGet GET /api/v1/webhooks/{id}/deliveries List a webhook's deliveries.
apiV1WebhooksIdGet GET /api/v1/webhooks/{id} Get one webhook.
apiV1WebhooksIdPatch PATCH /api/v1/webhooks/{id} Edit, pause or resume a webhook.
apiV1WebhooksIdRotateSecretPost POST /api/v1/webhooks/{id}/rotate-secret Issue a new signing secret.
apiV1WebhooksIdTestPost POST /api/v1/webhooks/{id}/test Send a test ping.
apiV1WebhooksPost POST /api/v1/webhooks Create a webhook.

apiV1EventsGet

ApiV1EventsGet200Response apiV1EventsGet(since, types, limit)

Read the account's event feed.

The same events the webhooks carry, for agents that cannot receive webhooks. Oldest first, kept 7 days. Page with the cursor: pass `next_cursor` from one answer as `since` in the next; `has_more` says whether to call again at once. `since=now` returns no events, only the current cursor — the way to start following from now. Only the events this credential may see are returned: each event needs the scope of what it is about (see the tag description), and a key pinned to campaigns, ad spaces or sites only sees events about those (and never the account-wide `conversion.summary`). The cursor moves past events you may not see, so a reader never stalls. Events are recorded only for accounts that have a live API key, a connected app or a webhook. `conversion.received` is never in the feed (webhook opt-in only).

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1EventsGetRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // string | Cursor from `next_cursor`, `now`, or omit for the whole 7 days. (optional)
    since: since_example,
    // string | Comma-separated event types to keep, e.g. `campaign.paused,ad.rejected`. (optional)
    types: types_example,
    // number (optional)
    limit: 56,
  } satisfies ApiV1EventsGetRequest;

  try {
    const data = await api.apiV1EventsGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
since string Cursor from `next_cursor`, `now`, or omit for the whole 7 days. [Optional] [Defaults to undefined]
types string Comma-separated event types to keep, e.g. `campaign.paused,ad.rejected`. [Optional] [Defaults to undefined]
limit number [Optional] [Defaults to 100]

Return type

ApiV1EventsGet200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
422 `since` is not a cursor, `types` names an unknown event, or `limit` is out of range. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksGet

ApiV1WebhooksGet200Response apiV1WebhooksGet()

List webhooks.

An API key or app sees the webhooks it created (the panel shows all of the account's). `available_events` lists the events this credential may subscribe to; `limit` is the per-account cap (20).

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksGetRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  try {
    const data = await api.apiV1WebhooksGet();
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

This endpoint does not need any parameter.

Return type

ApiV1WebhooksGet200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdDelete

ApiV1WebhooksIdDelete200Response apiV1WebhooksIdDelete(id)

Remove a webhook.

Deliveries still waiting for it are dropped and never sent.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdDeleteRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
  } satisfies ApiV1WebhooksIdDeleteRequest;

  try {
    const data = await api.apiV1WebhooksIdDelete(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]

Return type

ApiV1WebhooksIdDelete200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdDeliveriesDeliveryRedeliverPost

ApiV1WebhooksIdDelete200Response apiV1WebhooksIdDeliveriesDeliveryRedeliverPost(id, delivery)

Send a delivery again.

Delivered, failed or waiting — it is queued again with its original event id. The content comes from the 7-day event feed when the delivery itself no longer holds it (410 after that).

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdDeliveriesDeliveryRedeliverPostRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
    // number
    delivery: 56,
  } satisfies ApiV1WebhooksIdDeliveriesDeliveryRedeliverPostRequest;

  try {
    const data = await api.apiV1WebhooksIdDeliveriesDeliveryRedeliverPost(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]
delivery number [Defaults to undefined]

Return type

ApiV1WebhooksIdDelete200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 Queued. -
404 No such delivery on this webhook. -
409 It is being sent right now. -
410 `delivery_expired` — older than 7 days. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdDeliveriesGet

ApiV1WebhooksIdDeliveriesGet200Response apiV1WebhooksIdDeliveriesGet(id, status, limit)

List a webhook's deliveries.

The last 30 days, newest first.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdDeliveriesGetRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
    // 'pending' | 'sending' | 'delivered' | 'dead' (optional)
    status: status_example,
    // number (optional)
    limit: 56,
  } satisfies ApiV1WebhooksIdDeliveriesGetRequest;

  try {
    const data = await api.apiV1WebhooksIdDeliveriesGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]
status pending, sending, delivered, dead [Optional] [Defaults to undefined] [Enum: pending, sending, delivered, dead]
limit number [Optional] [Defaults to 50]

Return type

ApiV1WebhooksIdDeliveriesGet200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -
422 Unknown status. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdGet

ApiV1WebhooksPost201Response apiV1WebhooksIdGet(id)

Get one webhook.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdGetRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
  } satisfies ApiV1WebhooksIdGetRequest;

  try {
    const data = await api.apiV1WebhooksIdGet(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]

Return type

ApiV1WebhooksPost201Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdPatch

ApiV1WebhooksPost201Response apiV1WebhooksIdPatch(id, apiV1WebhooksIdPatchRequest)

Edit, pause or resume a webhook.

Omitted fields keep their value; the result is validated like a create. `status: paused` stops new events (read them from `/api/v1/events` meanwhile — kept 7 days) and holds what was already queued; `active` resumes and sends what was held. An event taken off the webhook drops its waiting deliveries. The secret stays.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdPatchOperationRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
    // ApiV1WebhooksIdPatchRequest
    apiV1WebhooksIdPatchRequest: ...,
  } satisfies ApiV1WebhooksIdPatchOperationRequest;

  try {
    const data = await api.apiV1WebhooksIdPatch(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]
apiV1WebhooksIdPatchRequest ApiV1WebhooksIdPatchRequest

Return type

ApiV1WebhooksPost201Response

Authorization

apiKey

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -
422 Validation error per field. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdRotateSecretPost

ApiV1WebhooksPost201Response apiV1WebhooksIdRotateSecretPost(id, apiV1WebhooksIdRotateSecretPostRequest)

Issue a new signing secret.

For `overlap_hours` (0..168, default 24) the previous secret keeps signing too — two `v1=` values — so you can switch whenever you like. `0` ends the old secret at once. The new `secret` is in the answer only.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdRotateSecretPostOperationRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
    // ApiV1WebhooksIdRotateSecretPostRequest (optional)
    apiV1WebhooksIdRotateSecretPostRequest: ...,
  } satisfies ApiV1WebhooksIdRotateSecretPostOperationRequest;

  try {
    const data = await api.apiV1WebhooksIdRotateSecretPost(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]
apiV1WebhooksIdRotateSecretPostRequest ApiV1WebhooksIdRotateSecretPostRequest [Optional]

Return type

ApiV1WebhooksPost201Response

Authorization

apiKey

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -
409 Rotated by someone else at the same moment. -
422 overlap_hours out of range. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksIdTestPost

ApiV1WebhooksIdTestPost200Response apiV1WebhooksIdTestPost(id)

Send a test ping.

Sends a signed `webhook.test` event now and answers what the receiver said (`status` delivered / pending / dead, `http_status`, `error`). A paused webhook only queues it.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksIdTestPostRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // number
    id: 56,
  } satisfies ApiV1WebhooksIdTestPostRequest;

  try {
    const data = await api.apiV1WebhooksIdTestPost(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
id number [Defaults to undefined]

Return type

ApiV1WebhooksIdTestPost200Response

Authorization

apiKey

HTTP request headers

  • Content-Type: Not defined
  • Accept: application/json

HTTP response details

Status code Description Response headers
200 OK -
404 Not one of this credential's webhooks. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]

apiV1WebhooksPost

ApiV1WebhooksPost201Response apiV1WebhooksPost(apiV1WebhooksPostRequest)

Create a webhook.

Returns the signing `secret` (`whsec_…`) once. Every delivery is a POST of the event envelope with `X-Integration-Event`, `X-Integration-Delivery` (the event id — dedupe on it, delivery is at-least-once), `X-Integration-Key-Id` and `X-Integration-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, &quot;<t>.<body>&quot;)>` (check every `v1`; during a secret rotation there are two). Answer 2xx within 10 s. Failures retry after 1 m, 5 m, 15 m, 1 h, 3 h, 6 h, 12 h, 24 h; a 4xx other than 408/429 is final; redirects are not followed. 20 failures in a row over a day pause the webhook (`paused_reason: auto_failing`). Events are queued within about a minute (state changes detected by the server&#39;s checks within about two to five). The URL must be a public `https://` address — private, loopback, link-local, metadata and reserved addresses are refused, when saved and again when sent. Each event must be one this credential may see (422 names the missing scope). Unknown body fields are refused.

Example

import {
  Configuration,
  WebhooksEventsApi,
} from 'goadserver-sdk';
import type { ApiV1WebhooksPostOperationRequest } from 'goadserver-sdk';

async function example() {
  console.log("🚀 Testing goadserver-sdk SDK...");
  const config = new Configuration({ 
    // Configure HTTP bearer authorization: apiKey
    accessToken: "YOUR BEARER TOKEN",
  });
  const api = new WebhooksEventsApi(config);

  const body = {
    // ApiV1WebhooksPostRequest
    apiV1WebhooksPostRequest: ...,
  } satisfies ApiV1WebhooksPostOperationRequest;

  try {
    const data = await api.apiV1WebhooksPost(body);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

// Run the test
example().catch(console.error);

Parameters

Name Type Description Notes
apiV1WebhooksPostRequest ApiV1WebhooksPostRequest

Return type

ApiV1WebhooksPost201Response

Authorization

apiKey

HTTP request headers

  • Content-Type: application/json
  • Accept: application/json

HTTP response details

Status code Description Response headers
201 Created — the only answer that carries `secret`. -
409 `webhook_limit` — the account has 20 webhooks. -
422 Validation error per field (url, events, description) or an unknown field. -

[Back to top] [Back to API list] [Back to Model list] [Back to README]