Skip to main content

Webhooks

Webhooks allow one to build or set up integrations which subscribe to certain events at agsync.com. When one of those events is triggered, AgSync will send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update an external system, trigger custom notifications, or journal events with the order.

Each webhook can be installed on an organization. Once installed, they will be triggered each time one or more subscribed events occurs for that organization.

Events​

When configuring a webhook, one can choose which events are preferred to receive payloads for. One can even opt-in to all current and future events.

Only subscribing to the specific events planned for handling is useful for limiting the number of HTTP requests to the client server. One can change the list of subscribed events through organization settings UI anytime.

By default, webhooks are not set up and are therefore optional.

Each event corresponds to a certain set of actions that can happen to the client organization. For example, if subscribed to the field_changed event one will receive detailed payloads every time a field is created, changed, or deleted.

The available events are:

NameDescription
*All events in the system including additional future events
customer_changedAny time a customer is created, changed or deleted
farm_changedAny time a farm is created, changed or deleted
field_changedAny time a field is created, changed or deleted
zone_changedAny time a zone is created, changed or deleted
order_changedAny time an order is created, changed or deleted

Setup​

Setting up webhooks both through API Access and Manual Setup require AgSync login credentials and access. Additionally, secret strings may be requested of users.

Webhook API Access​

Webhooks for AgSync have Swagger Documentation.

These endpoints can only be utilized if AgSync API access has been granted previously.

To fetch, create, update, or delete webhook events using the Swagger Documentation, try the following:

  1. Paste an access token into the access_token textbox at the top of the page.
  2. Click 'Explore'.
  3. Expand the desired HTTP method and endpoint, provide any required parameters.
  4. Click the 'Try it out!' button.

The curl request, request URL, response body, response code, and response headers will be returned.

Webhook Secrets​

Setting up webhooks manually will require a secret. This secret is used for security purposes and determines authenticity regarding requests.

A secret is a string of characters. It should follow the same rules as a strong password. Some tips for setting up a good secret are as follows:

  • It should have at least 8 characters.
  • It should contain both numbers and letters.
  • It should not contain easily guessed words, such as the organization name.

Note, a secret can also be provided by a random string generator at an appropriate string length. Many tools that fulfill this functionality can be found online.

Manual Setup for Webhooks​

It is possible to set webhook events manually. This can be done with the AgSync Web Application.

To set up your webhook events manually, navigate to the web application and select Webhooks under Organization Settings.

To add a new webhook event try the following:

  1. Click the blue 'Add Webhook' button near the top of the page.
  2. Paste your URL and webhook secret in the textboxes provided and select the 'Let me choose' radio button to see all webhook event options.
  3. Once all desired events have been selected, click the Save Changes button at the bottom of the popup page.

Payloads​

Each event type has a specific payload format with the relevant event information.

In addition to the fields documented for each event, webhook payloads include the user who performed the event (Sender) as well as the account (AccountId) which the event occurred on.

Delivery Headers​

HTTP requests made to a webhook's configured URL endpoint will contain several special headers:

HeaderDescription
X-AgSync-EventName of the event that triggered the delivery
X-AgSync-SignatureHMAC hex digest of the payload, using the hook's secret as the key

Signature​

A signature is sent with every request to verify that it came from AgSync. The signature is a HMAC SHA1 computed hash using the secret key setup with the webhook and the body of the request. The hyphens are also removed from the hash.

Here is a C# example verifying the hash.

private bool Verify(string hash, string body, string key)
{
    var keyBytes = Encoding.UTF8.GetBytes(key);
    var bodyBytes = Encoding.UTF8.GetBytes(body);

    var hmac = new HMACSHA1(keyBytes);
    var result = hmac.ComputeHash(bodyBytes);
    var cleanedResult = BitConverter.ToString(result).Replace("-", "");

    return cleanedResult == hash;
}