Webhooks API

Webhooks tell your server when the store's promotions and discounts change, so you don't have to poll. Create a subscription for each topic you need, and Abra sends a POST with a JSON body to your HTTPS URL. To check that a request came from Abra, see Verifying Webhooks.

Event topics

Each subscription receives one topic:

• promotions/create: a promotion was created.

• promotions/update: a promotion changed.

• promotions/delete: a promotion was deleted.

• discounts/create: a discount was created or attached.

• discounts/update: a discount changed.

• discounts/delete: a discount was deleted.

To get several topics at the same URL, create one subscription per topic.

Payload

Each delivery is a POST with Content-Type: application/json and this body:

• topic: the topic.

• shopDomain: the store's myshopify.com domain.

• resource: the promotion or discount, in the same shape the API returns it. For promotions/delete and discounts/delete it only has the id.

• occurredAt: when Abra sent the delivery (ISO 8601).

The headers X-Abra-Topic, X-Abra-Webhook-Id (the subscription ID), X-Abra-Delivery-Id (unique per delivery) and X-Abra-Delivery-Timestamp come with every delivery. If the subscription has a secret, X-Abra-Signature holds sha256= and an HMAC-SHA256 of the raw body; see Verifying Webhooks.

Abra sends each delivery once and waits up to 5 seconds. Any response other than 2xx, including a redirect, is a failure. After 4 failures in a row the subscription's status becomes DISABLED and deliveries stop; a successful delivery resets the count. To start again, delete the subscription and create it again.

The webhook subscription object

Webhook endpoints return subscriptions in this shape, in the data field of the response.

List webhook subscriptions

GET /v1/partner/webhooks

Returns all of the store's webhook subscriptions, newest first, in one response. Disabled subscriptions are included, so check status.

Example request

curl "$ABRA_API_BASE/v1/partner/webhooks" \
  -H "Authorization: Bearer $ABRA_API_TOKEN"

Response

200 OK. data is an array of webhook subscriptions. Their fields are listed in The webhook subscription object.

Errors

Create a webhook subscription

POST /v1/partner/webhooks

Subscribes an HTTPS URL to one topic. The URL must be public: hosts that resolve to private or reserved addresses are rejected. The subscription starts ACTIVE.

Set a secret to have every delivery signed (see Verifying Webhooks). The API never returns the secret, so keep your own copy. A store can subscribe the same topic and URL only once, even while that subscription is disabled.

Request body

Example request

curl -X POST "$ABRA_API_BASE/v1/partner/webhooks" \
  -H "Authorization: Bearer $ABRA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "promotions/create",
    "url": "https://example.com/webhooks/promotions",
    "secret": "whsec_your_signing_secret"
  }'

Response

201 Created. Returns the webhook subscription in data. Its fields are listed in The webhook subscription object.

Errors

Get a webhook subscription

GET /v1/partner/webhooks/{id}

Returns one subscription. Use it to check status, consecutiveFailures and lastDeliveryAt.

Path parameters

Example request

curl "$ABRA_API_BASE/v1/partner/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $ABRA_API_TOKEN"

Response

200 OK. Returns the webhook subscription in data. Its fields are listed in The webhook subscription object.

Errors

Delete a webhook subscription

DELETE /v1/partner/webhooks/{id}

Deletes the subscription, so no more deliveries are sent to it. Returns 204 with no body.

Path parameters

Example request

curl -X DELETE "$ABRA_API_BASE/v1/partner/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $ABRA_API_TOKEN"

Response

204 No Content. The response has no body.

Errors

This page is generated from the Abra API specification (build bc96ccc) · ref f2e99308125d. Edits made in Pylon are overwritten.