> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awardforce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive event notifications from Award Force using webhooks configured by program managers.

## Manage webhooks

<AccordionGroup>
  <Accordion title="Create a webhook">
    <Steps>
      <Step title="In Award Force, go to Settings > Integrations > Webhooks" />

      <Step title="Click New webhook" />

      <Step title="Enter Name" />

      <Step title="Enter Webhook URL" />

      <Step title="Use the auto-generated Signing key or create a new one" />

      <Step title="Select Event subscriptions" />

      <Step title="Specify notification email addresses if needed. Separate each address with a comma (,) or semicolon (;)" />

      <Step title="Click Save" />
    </Steps>
  </Accordion>

  <Accordion title="Edit webhook">
    <Steps>
      <Step title="In Award Force, go to Settings > Integrations > Webhooks" />

      <Step title="Click the name of the webhook to edit" />

      <Step title="Make your changes" />

      <Step title="Click Save" />
    </Steps>
  </Accordion>

  <Accordion title="Delete a webhook">
    <Steps>
      <Step title="In Award Force, go to Settings > Integrations > Webhooks" />

      <Step title="Select the checkbox next to the webhook, then use the Action button to delete it" />

      <Step title="Click OK in the confirmation dialog" />
    </Steps>
  </Accordion>
</AccordionGroup>

## Webhook payloads

Webhook payloads are provided in JSON format and always contain the following attributes:

<ParamField header="event" type="string" required>
  Enumerated string with possible values being one of the events described in the following sections.
</ParamField>

<ParamField header="timestamp" type="string" required>
  ISO 8601 formatted datetime value, for example `2020-01-01T00:00:00Z`.
</ParamField>

<ParamField header="trigger" type="string" required>
  Machine-readable event key that fired the webhook. Enumerated string with possible values matching the event codes described in the following sections.
</ParamField>

<ParamField header="source" type="string" required>
  Enumerated string with the following possible values:

  * `ui` (default)
  * `api`
</ParamField>

### Signature

Use the `Signature` header to validate the webhook payload.

The signature value is generated with this algorithm, using the **Signing key** specified in the webhook and the JSON payload:

<CodeGroup>
  ```php PHP theme={null}
  $signature = hash_hmac('sha256', $payloadJsonString, $signingKey);
  ```

  ```js JavaScript theme={null}
  const crypto = require('crypto');
  const signature = crypto
    .createHmac('sha256', signingKey)
    .update(payloadJsonString)
    .digest('hex');
  ```

  ```python Python theme={null}
  import hmac
  import hashlib
  signature = hmac.new(
      signingKey.encode(),
      payloadJsonString.encode(),
      hashlib.sha256
  ).hexdigest()
  ```

  ```csharp C# theme={null}
  using System.Security.Cryptography;
  using System.Text;
  var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signingKey));
  var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payloadJsonString));
  var signature = BitConverter.ToString(hash).Replace("-", "").ToLower();
  ```

  ```java Java theme={null}
  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  Mac mac = Mac.getInstance("HmacSHA256");
  SecretKeySpec keySpec = new SecretKeySpec(
      signingKey.getBytes("UTF-8"), "HmacSHA256");
  mac.init(keySpec);
  byte[] hash = mac.doFinal(payloadJsonString.getBytes("UTF-8"));
  StringBuilder sb = new StringBuilder();
  for (byte b : hash) sb.append(String.format("%02x", b));
  String signature = sb.toString();
  ```
</CodeGroup>

Generate the same value in your endpoint and compare it with the `Signature` header value.

### Available event subscriptions

<AccordionGroup>
  <Accordion title="Assignment events">
    | Event                  | Description                                         |
    | ---------------------- | --------------------------------------------------- |
    | `assignment_completed` | Fired when an assignment is completed by a judge.   |
    | `assignment_created`   | Fired when a new assignment is created for a judge. |
  </Accordion>

  <Accordion title="Document events">
    | Event              | Description                                     |
    | ------------------ | ----------------------------------------------- |
    | `document_created` | Fired when a new document is added to an entry. |
    | `document_deleted` | Fired when a document is removed from an entry. |
    | `document_updated` | Fired when an existing document is updated.     |
  </Accordion>

  <Accordion title="Entry events">
    | Event                    | Description                                             |
    | ------------------------ | ------------------------------------------------------- |
    | `collaborator_invited`   | Fired when a collaborator is invited to an entry.       |
    | `entry_category_changed` | Fired when an entry's category is changed.              |
    | `entry_chapter_changed`  | Fired when an entry's chapter is changed.               |
    | `entry_copied`           | Fired when an entry is copied.                          |
    | `entry_created`          | Fired when a new entry is created.                      |
    | `entry_deleted`          | Fired when an entry is deleted.                         |
    | `entry_eligible`         | Fired when an entry is marked as eligible.              |
    | `entry_ineligible`       | Fired when an entry is marked as ineligible.            |
    | `entry_moderated`        | Fired when an entry is moderated.                       |
    | `entry_resubmitted`      | Fired when an entry is resubmitted by the entrant.      |
    | `entry_submitted`        | Fired when an entry is submitted by the entrant.        |
    | `entry_tagged`           | Fired when a tag is applied to an entry.                |
    | `entry_updated`          | Fired when an existing entry is updated.                |
    | `field_value_updated`    | Fired when a custom field value is updated on an entry. |
    | `review_task_created`    | Fired when a review task is created for a reviewer.     |
    | `review_task_submitted`  | Fired when a review task is submitted by a reviewer.    |
  </Accordion>

  <Accordion title="Order payment events">
    | Event                   | Description                                            |
    | ----------------------- | ------------------------------------------------------ |
    | `order_payment_pending` | Fired when an order payment is marked as pending.      |
    | `order_payment_success` | Fired when an order payment is completed successfully. |
  </Accordion>

  <Accordion title="User events">
    | Event                   | Description                                       |
    | ----------------------- | ------------------------------------------------- |
    | `membership_registered` | Fired when a new user registers or is created.    |
    | `role_granted`          | Fired when a role is granted to a user.           |
    | `user_updated`          | Fired when an existing user's profile is updated. |
  </Accordion>
</AccordionGroup>