Webhooks

GunTab can send your app real-time updates about your transactions, so you know when to prepare a shipment, when to ship, and when you've been paid.

What are webhooks?

Webhooks are HTTP POST requests that GunTab makes to the URL of your choice. These requests include a JSON-formatted payload with details about a transaction. These requests occur when GunTab updates a transaction to one of the webhook-enabled transaction statuses.

How do I configure webhooks?

Go to Account > Webhooks to add up to 3 webhook endpoints, and review your existing webhook endpoints. Webhooks will be sent to every endpoint you configure, for every eligible transaction status.

What are the webhook-enabled transaction statuses?

When a transaction enters any one of these statuses, a webhook is sent:

What do the JSON payloads look like?

Here is an example JSON payload that would be posted to your webhook endpoint:

{
  "invoice_id": "d7124f45-4766-4240-a7f1-ccfda83b2ea9",
  "seller_order_id": "55555",
  "status": "pending_outbound_shipment",
  "transaction_id": "4b5f0b94-cabd-440c-8a83-8616beb50ddc"
}

The values are defined as follows:

Can webhook payloads be verified?

Yes, all webhook payloads are signed so you can verify them. You should use your webhook's "signing secret key" to generate your own HMAC, and compare it to GunTab's HMAC included with each webhook payload. Here's how it works:

If verifying the signature exceeds your technical capabilities, there is a simpler but less secure alternative. You can add a token parameter to the endpoint URL you enter in GunTab, with a random value that you generate. Then when you receive a webhook payload from GunTab, you check to confirm the token parameter has the value you generated. If the strings don't match, the webhook payload may not be legitimate.

What is the recommended usage for a seller?

If you are a seller, we recommend the following usage:

  1. pending_payment_processing: Package the order for shipment (but do not send).
  2. pending_outbound_shipment: Send the shipment and "mark as shipped" in GunTab.
  3. pending_outbound_shipment_delivery: No action necessary, this status is informational. GunTab will notify the buyer of delivery.
  4. pending_buyer_inspection_period: Expect your disbursement to be sent in 3 days or less.
  5. pending_disbursement_processing: No action necessary, this status is informational. Expect your disbursement to be visible in your online banking in 1-2 business days.
  6. succeeded: No action necessary, this status is informational. Your disbursement should be visible in your online banking.

Be on the lookout for status values that indicate a problem:

Can I simulate/test webhooks?

Yes. Go to Account > Webhooks, select a webhook then click the "Test" button. For each test you can select which status you want to POST to your endpoint.

Can I see webhook results?

Yes. Go to Account > Webhooks, select a webhook then see the "last used" information, including: