Webhooks

This feature is only available in the Plus subscription plan. You can upgrade your plan from the Settings dialog in the admin side menu

What is a webhook?

A webhook is a single message of an event type sent by ACF to an HTTPS endpoint of your choosing. A webhook contains a JSON payload in the body with details related to the event.

Available event types are:

As you can see, these event types closely match the available scopes in ACF (with the exception of customers and orders, which are planned for a later release) and are fired whenever the custom fields for the scope are changed, either via the ACF editor or via an ACF import.

The JSON payload structure for the above event types is:

{
  shop: "awesomewebshop.myshopify.com",
  id: 123456789012,
  metafields: [
    { id: {metafield_id},
      namespace: {namespace},
      key: {key},
      value: {value}
    },
    { id: {metafield_id},
      namespace: {namespace},
      key: {key},
      value: {value}
    },
    ...
    ]
  }

The payload id refers to the id of the object in question, so for product.update it is the product id, for page.update the page id, etc.

Note: for the event types product_type.update and vendor.update, the id will be a string, denoting the alphanumeric product type and vendor respectively

The metafields array is the up-to-date set of metafields for the id. The type of value depends on the type of the Metafield - for repeatable fields, the value will always be an array.

ACF also provides event types related to activities:

The JSON payload structure for the above event types is:

{
  id: "unique-activity-id",
  shop: "awesomewebshop.myshopify.com"
  type: "import" | "export",
  scope: "product" | "page" etc,
  status: "started" | "completed" | "failed" | "stopped",
  items: 9999,
  errors: 0,
  file: "https://cdn.accentuate.cloud/path/to/file"
}

Enabling webhooks in ACF

From the Settings dialog (available from the admin side menu), click the "Webhooks" tab and enable the webhooks:

Click the Control panel button to open a new dialog to add the HTTPS endpoint(s) to handle the webhooks.

When setting up the endpoints for your webhook subscription, you can select to only receive selected event types per endpoint or have a single endpoint receive all events regardless of the event type.

Tip: you can send your webhooks to an automation service such as Zapier or IFTTT. The webhooks can work as triggers in a workflow, for example, to send an SMS or a Slack message

Responding to webhooks

After receiving a webhook using an HTTPS endpoint, it's important to respond to the request with a 200 OK as quickly as possible.

A common pattern is to store the payload in a message queue for later processing by a background worker. This reduces the chance of the request timing out, and the webhook delivery counting as a failure.

This is normally not something you need to consider when using an automation platform that handles the technical stuff for you.

Delivery schedule

ACF attempts to deliver each webhook message based on a retry schedule with exponential backoff. Each message is attempted based on this schedule:

  • Immediately

  • 5 seconds

  • 5 minutes

  • 30 minutes

  • 2 hours

  • 5 hours

  • 10 hours

  • 20 hours

After the above attempts the message will be marked as failed. If an endpoint is removed or disabled, delivery attempts to the endpoint will be disabled as well.

Resend webhooks

If for some reason, your endpoints are unavailable for an extended period of time (more than 20 hours) or the automatic delivery schedule doesn't fit your needs, you can resend your webhooks manually via the Control panel's Logs tab.

PreviousAllow customers to change their field valuesNextAPI

Last updated