Help Center Log in

Webhooks Reference

How they work

Webhook URLs will receive a POST request with JSON data related to the event that triggered the webhook.

See Events below for supported events and the associated JSON payloads.

Error handling

There are things that can go wrong even before a request reaches its destination (e.g. DNS resolution error, sudden network failure, etc.) and even if it does, the target system may not always be able to correctly process the request. This is why the notification delivery system is built to handle these failures.

Our webhook delivery system uses response status to determine whether a request has been successful or not.

  • 2XX response codes: The request is considered successful and the notification is considered as delivered, no retry needed.

  • Any other response status or error (such as connection error, timeout, etc.) is handled as an unsuccessful delivery attempt and the task is rescheduled for later.

Retries

If a webhook delivery fails, it gets retried. We use an exponential backoff strategy to determine how long to wait before attempting the delivery again.

We'll retry a webhook delivery up to 20 times, after which the delivery will be marked as retries exhausted and retries will stop.

Events

screenshot_set.approved

This event is fired when a set of screenshots is ready for download

Payload
{
  "id": "evt_{{uuid-of-event}}", // unique ID for this event
  "type": "event",
  "created_at": "2023-01-01T10:52:11.822-05:00",
  "topic": "screenshot_set.approved",
  "data": {
    "object": {
      "type": "screenshot_set",
      "id": "uuid-of-screenshot-set",
      "campaign_id": "uuid-of-campaign", // ID of the Campaign in Ad Reform
      "created_at": "2023-01-01T10:51:23.961-05:00",
      "status": "approved", // this will always be "approved"
      "instructions": "",   // the special instructions sent in the original request
      "review_notes": "",   // notes from Ad Reform if there was a problem with the screenshot
      "screenshots": [
        {
          "type": "screenshot",
          "id": "uuid-of-screenshot", // ID of the Screenshot in Ad Reform
          "status": "uploaded",
          "image_url": "https://app.adreform.com/path/image.png",
          "device": "Desktop",
          "site": {
            "url": "https://theverge.com",
            "host": "theverge.com"
          },
          "ad": {
            "type": "ad",
            "id": "uuid-of-ad", // ID of the Ad in Ad Reform
            "status": "uploaded",
            "lookup_key": "ad-lookup-key-if-present", // or null
            "name": "name-if-present", // name of the Ad in Ad Reform
            "external_id": null,
            "preview_image_url": "https://app.adreform.com/path/image.png",
            "width": 300,
            "height": 250,
            "html_url": "https://app.adreform.com/path/to/ad/in-webui",
            "media": {
              "type": "image_file" // see Media object in docs for possible values
            },
            // if ad was synced from Xandr, this will be present
            "xandr_creative": {
              "xandr_id": 440600236,
              "name": "ad_reform_300x250",
              "line_item": {
                "xandr_id": 21352428,
                "name": "Example Display-EN_O6X6TSIFL-1261",
                "state": "active"
              }
            }
          },
          // if a bucket and key_prefix were specified
          // as `subscribers` in the Screenshot Request
          // we'll include info about the S3 objects here
          "s3_objects": [
            {
              "bucket": "my-bucket-name",   // bucket containing the screenshot
              "key": "key-prefix/uuid.png", // object key for the screenshot
              "status": "uploaded"          // will be "upload_failed" if there was a problem uploading
            }
          ]
        },
        {
          "type": "screenshot",
          "id": "uuid",
          "status": "uploaded",
          "image_url": "https://app.adreform.com/path/image2.png",
          "device": "Desktop",
          "site": {
            "url": "https://espn.com",
            "host": "espn.com"
          },
          "ad": {
            "id": "uuid-of-ad",
            "status": "uploaded",
            "lookup_key": "ad-lookup-key-if-present",
            "type": "ad",
            "name": "name-if-present",
            "external_id": null,
            "preview_image_url": "https://app.adreform.com/path/image.png",
            "width": 300,
            "height": 250,
            "html_url": "https://app.adreform.com/path/to/ad/in-webui",
            "media": {
              "type": "image_file"
            }
          },
          "s3_objects": [
            {
              "bucket": "my-bucket-name",
              "key": "key-prefix/uuid.png",
              "status": "uploaded"
            }
          ],
          "xandr_creative": null
        }
      ]
    }
  }
}

Objects

ad

This object contains data about the ad creative. Notable fields include:

status

screenshot

This object contains data about the screenshot. Notable fields include:

status

Last updated

Was this helpful?